Claude Code: чем отличаются hooks, skills и слэш-команды

В Claude Code навык, слэш-команда и hook не образуют три взаимоисключающих способа автоматизации. Навык (skill) хранит инструкции и вспомогательные файлы; слэш-команда позволяет вызвать его через /имя; hook запускает обработчик в определённой точке жизненного цикла. Если вы каждый раз объясняете одинаковую процедуру проверки, начните с навыка. Если проверка должна срабатывать перед конкретным инструментом, нужен hook. Для смены модели или управления контекстом сначала посмотрите встроенные команды.

Есть важная поправка к старым руководствам: по документации Claude Code, проверенной 4 октября 2026 года, пользовательские команды уже объединены с навыками. Старый файл .claude/commands/review-note.md и новый .claude/skills/review-note/SKILL.md создают вызов /review-note. Существующие команды продолжают работать; переносить их все ради нового названия не требуется.

Что выбрать для вашей задачи

Выбирайте по необходимому результату, а затем определяйте, кто и когда запускает работу.

Встроенные команды и навыки, поставляемые вместе с Claude Code, тоже различаются. Большинство встроенных команд выполняют фиксированную логику CLI. Поставляемые навыки, например /claude-api, передают Claude инструкции для работы. Одинаковый начальный символ / не означает одинаковую реализацию и не обещает выполнение без модели или расхода токенов. В справочнике команд такие навыки помечены как Skill.

Навык можно вызывать вручную или по контексту

По умолчанию навык доступен обоим: вы можете написать /имя-навыка, а Claude — загрузить его, если описание соответствует задаче. Поэтому разделение «команды всегда ручные, навыки всегда автоматические» неверно.

В начале SKILL.md можно задать два разных ограничения:

Это параметры для разных участников, а не два способа спрятать пункт меню. При user-invocable: false вручную набранный вызов тоже не запускает навык. Для ручной процедуры оставьте этот параметр по умолчанию и задайте disable-model-invocation: true. Точное поведение описано в управлении вызовом навыков.

Ручной запуск особенно полезен, когда важны выбранная ветка, готовность данных или согласованный момент действия. Сам по себе он не подтверждает разрешение на каждую дальнейшую операцию: инструкции навыка и настройки разрешений остаются отдельными частями системы.

Пример: короткий разбор одного файла

Ниже — небольшой навык, который готовит замечания к коду. Он не устанавливает пакеты, не запускает тесты и не предлагает автоматически исправлять всё найденное. Для использования нужен работающий Claude Code и доступный для чтения файл в открытом проекте.

Создайте в своём проекте .claude/skills/review-note/SKILL.md с таким содержимым. Имя SKILL.md должно быть именно таким; открывающая строка --- должна быть первой строкой файла.

---
name: review-note
description: Готовит короткий разбор одного файла с конкретными замечаниями к коду.
argument-hint: путь-к-файлу
disable-model-invocation: true
---

Разбери файл $ARGUMENTS.

1. Если путь не указан, попроси указать один файл и остановись.
2. Прочитай файл. Если он недоступен, сообщи об этом и не выдумывай содержимое.
3. Найди ошибки логики, обработки входных данных и ошибок выполнения.
4. Для каждого замечания укажи строку, последствие и предлагаемое исправление.
5. Если конкретных замечаний нет, напиши «Замечаний в рамках этого разбора нет».

Не редактируй файлы, не запускай команды и не обращайся к внешним сервисам.
Не утверждай, что тесты проходили: здесь выполняется чтение и разбор кода.

После сохранения проверьте наличие навыка через /skills и вызовите его, например:

/review-note src/example.ts

Замените src/example.ts реальным путём. Текст после имени попадёт в $ARGUMENTS. Успешный результат — ответ о выбранном файле с конкретными замечаниями и строками либо явное сообщение, что замечаний не найдено. Если файл не существует, ожидается сообщение об отсутствии файла. Это проверяет понятность процедуры, но не доказывает, что модель найдёт все ошибки.

Запреты в теле примера являются инструкциями Claude. Они не создают техническую изоляцию инструментов. Для первого знакомства мы не добавляем автоматических разрешений: действуют обычные настройки вашей среды.

Когда процедура вырастет, рядом с SKILL.md можно положить examples.md, справочный файл или каталог scripts/. В основном файле укажите, когда читать каждый материал. Это позволяет загружать детали по необходимости, а не превращать одну инструкцию в большой справочник. Официальная документация описывает такую структуру как часть пакета навыка. Соседний обзор направлений применения навыков поможет различить работу с документами, проверку веб-приложений и собственные процедуры команды; приведённые там перечни относятся к дате того обзора.

allowed-tools не означает «только эти инструменты»

Если в метаданных указано allowed-tools: Read, Claude получает предварительное разрешение на Read в ходе вызова навыка. Остальные инструменты при этом не исчезают: для них продолжают действовать обычные разрешения. Поэтому такой параметр нельзя описывать как гарантию режима только для чтения.

Для удаления инструментов из доступного набора предназначен disallowed-tools. И разрешение allowed-tools, и ограничение disallowed-tools заканчиваются при следующем сообщении пользователя. Текст вызванного навыка при этом остаётся в разговоре на последующих ходах, хотя при сокращении контекста действуют ограничения его сохранения. Это разные сроки действия. См. разрешения навыков и жизненный цикл их содержимого.

В организациях есть дополнительное условие: при allowManagedPermissionRulesOnly Claude Code версии 2.1.282 и новее игнорирует allowed-tools из затронутых этой политикой источников, в том числе пользовательских и проектных навыков. Такие инструменты проходят через управляемые правила организации и обычный запрос разрешения. Описание управляемой политики важнее примера из чужого репозитория.

Hook привязывает обработчик к событию

У настройки hook три части: событие, фильтр (matcher) и обработчик. Событие определяет момент, например PreToolUse перед вызовом инструмента. Фильтр выбирает подходящие вызовы, например Edit и Write. Обработчик выполняет работу и возвращает результат.

В текущей документации описаны пять типов обработчиков:

Не каждый тип поддерживается каждым событием. Перед настройкой проверьте сочетание в справочнике hooks; примеры для одного события нельзя переносить на другое только заменой имени.

Фиксирован именно момент запуска обработчика при подходящем событии, а не правильность его ответа. Скрипт может выдавать воспроизводимое решение по строго заданному правилу. prompt и agent принимают решение с участием модели: они добавляют задержку и расход на её работу, а результат зависит от формулировки и доступных данных. Hooks допускают такие оценки; запрещать любые сложные суждения в них неправильно. Однако оценка «изменение достаточно качественное» не становится гарантией качества только потому, что выполняется автоматически. Руководство отдельно объясняет модельные обработчики.

Пример hook: не давать Edit и Write менять учебный файл

Для первого опыта удобнее выбрать правило, результат которого легко проверить. Наш обработчик запрещает инструментам Edit и Write менять файл с именем demo-locked.txt. Он ничего не записывает и не выполняет строку из входного JSON.

Нужен Node.js, доступный через команду node. В корне своего учебного проекта создайте каталог scripts, если его ещё нет, и сохраните следующий скрипт как scripts/check-demo-lock.mjs:

import fs from 'node:fs';
import path from 'node:path';

function block(message) {
  console.error(message);
  process.exit(2);
}

let event;
try {
  event = JSON.parse(fs.readFileSync(0, 'utf8'));
} catch {
  block('Некорректный JSON события.');
}

if (event?.hook_event_name !== 'PreToolUse') {
  block('Этот обработчик предназначен только для PreToolUse.');
}

if (!['Edit', 'Write'].includes(event.tool_name)) {
  process.exit(0);
}

const filePath = event.tool_input?.file_path;
if (typeof filePath !== 'string' || filePath.length === 0) {
  block('Во входе Edit/Write отсутствует file_path.');
}

const basename = path.win32.basename(path.posix.basename(filePath));
if (basename === 'demo-locked.txt') {
  block('Учебный файл demo-locked.txt менять запрещено.');
}

process.exit(0);

Проверьте скрипт отдельно от Claude Code. В терминале из корня учебного проекта передайте ему два небольших входа:

printf '%s\n' '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"notes/demo-locked.txt"}}' | node scripts/check-demo-lock.mjs
echo "$?"

printf '%s\n' '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"notes/draft.txt"}}' | node scripts/check-demo-lock.mjs
echo "$?"

В первом случае ожидаются сообщение о запрете в стандартном потоке ошибок и код 2. Во втором — пустой вывод и код 0. Такие проверки можно выполнить без установленного hook: они проверяют скрипт и его входные данные.

Для привязки к Claude Code добавьте эту запись в объект hooks проектного файла .claude/settings.local.json. Если файл уже содержит настройки, объедините записи: не заменяйте весь файл и не удаляйте другие обработчики.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^(Edit|Write)$",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR/scripts/check-demo-lock.mjs\""
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR указывает на корень проекта, поэтому имя скрипта совпадает с местом его сохранения. Показанная командная строка рассчитана на среду, где используемая оболочка раскрывает переменные в таком виде. Проверяйте это в своём окружении, особенно при переносе между операционными системами.

Затем откройте /hooks: запись должна появиться у PreToolUse. В учебной сессии проверьте попытку записи именно через Edit или Write. Ожидаемый результат при обращении к demo-locked.txt — отказ перед выполнением этого вызова. Если настройки не появились, сначала проверьте JSON, расположение файла и наличие скрипта. Наблюдатель за файлами обычно подхватывает изменения автоматически; если этого не произошло, перезапустите сеанс. Эти шаги соответствуют официальному руководству по настройке.

Мы проверили синтаксис приведённых JSON/YAML и работу скрипта на искусственных входах: запрет учебного имени, разрешённое имя, пропущенный путь и повреждённый JSON. Настоящий вызов инструментов Claude Code и оценку моделью в рамках этой проверки не запускали.

Это учебная проверка имени, а не защита файловой системы. Она не охватывает Bash, другие инструменты записи, внешние процессы или обходные пути к тому же файлу. Используйте её, чтобы разобраться в связи события, фильтра и результата; для реального ограничения доступа нужны подходящие разрешения и более полная проверка угроз.

Что означают коды выхода и когда поздно блокировать

Для нашего command-обработчика на PreToolUse код 0 без JSON означает «возражений от обработчика нет». Он не выдаёт разрешение на инструмент: дальше действует обычная процедура проверки прав. Код 2 блокирует этот вызов, а сообщение из стандартного потока ошибок объясняет причину Claude. Это точный смысл выбранного примера, а не универсальное правило для всех событий.

См. таблицу действий для кода 2. Для большинства событий другой ненулевой код с пустым выводом означает неблокирующую ошибку обработчика, но у событий есть исключения. Валидный структурированный JSON также может определять результат по своим правилам. Поэтому в одном небольшом обработчике удобнее выбрать один протокол: в нашем примере это только код выхода и сообщение об ошибке, без JSON на выходе. Полное описание протокола потребуется для более сложных решений.

У модельного prompt-обработчика другой формат ответа: ok и reason. Например, при Stop отрицательное решение может заставить Claude продолжать работу. Если условие завершения сформулировано слишком широко, получатся повторные оценки и лишние продолжения. Задавайте достижимый критерий и предусмотрите случай, когда продолжать бессмысленно; не используйте бесконечную проверку «сделай идеально».

Когда объединять навык и hook

Комбинация полезна, когда у частей разные задачи. Например, /release-note запускает по вашему выбору навык подготовки описания релиза. Навык задаёт порядок: прочитать изменения, отметить несовместимости, перечислить проверки. Отдельный hook проверяет конкретный аргумент инструмента перед записью. Один обеспечивает процедуру работы, другой — своевременный запуск узкой проверки.

Не добавляйте hook только потому, что рядом уже есть навык. Если вам нужен один разбор файла, достаточно примера /review-note. Если проверка должна повторяться при каждом подходящем вызове инструмента, настройте событие. Для доступа к внешним данным сначала должен существовать соответствующий инструмент или подключение: текст навыка сам по себе такого доступа не создаёт.

При сочетании частей учитывайте их сроки действия. Hooks из настроек зависят от области файла: ~/.claude/settings.json относится к личным проектам на машине, .claude/settings.json — к общим настройкам проекта, .claude/settings.local.json — к локальным настройкам этого проекта. Hook можно описать и в метаданных навыка. После вызова навыка такой обработчик сейчас остаётся зарегистрированным до конца сеанса; once: true снимает его после первого успешного выполнения. Hooks субагента действуют лишь пока работает этот субагент. Это не тот же срок, что у allowed-tools. См. расположение hooks и hooks в навыках и агентах.

Если одному событию соответствуют несколько hooks, они выполняются параллельно, а результаты объединяются после завершения. Отказ одного не предотвращает побочный эффект другого. Для решений PreToolUse приоритет идёт от наиболее строгого: deny, затем defer, ask, allow. Асинхронный обработчик также не может задним числом предотвратить уже выполненное действие. Эти ограничения важны, например, когда рядом с проверкой стоит отправка данных или изменение файла. Правила объединения результатов объясняют, почему наличие запрета ещё не означает, что остальные обработчики ничего не сделали.

Частые вопросы

Нужно ли переносить старые пользовательские команды в skills?

Нет, существующие .claude/commands/*.md продолжают работать. Перенос имеет смысл, если нужны вспомогательные файлы и более удобная структура пакета. Новую процедуру обычно удобнее оформить как навык, но старый файл не становится ошибкой только из-за своего каталога. Это прямо указано в документации навыков.

Какой командой вызвать навык для работы с Claude API?

Используйте /claude-api; например, /claude-api migrate запускает предусмотренную процедуру миграции. Это навык, поставляемый с Claude Code, а не команда установки SDK. Он может включаться и автоматически, когда код импортирует anthropic или @anthropic-ai/sdk. Доступность конкретных подкоманд зависит от версии: сверяйтесь с разделом о проектах Claude API, а текущий список своей среды смотрите через /help и /skills.

Почему навык виден, но ограничение из его метаданных не работает?

Проверьте регистр SKILL.md, первую строку ---, корректность YAML и точное написание параметра. Неизвестное поле может быть проигнорировано, а при повреждённом YAML навык может загрузиться без заданных полей. Поэтому присутствие в списке не доказывает, что disable-model-invocation или инструментальные ограничения применились. Правила разбора описаны в справочнике метаданных.

Hook надёжнее навыка?

Для запуска проверки в заданный момент hook подходит лучше: его вызывает событие, а не решение Claude вспомнить инструкцию. Но надёжность самой проверки зависит от обработчика и охвата. prompt и agent по-прежнему используют модель, а узкий скрипт проверяет только запрограммированные случаи. Навык удобнее для объяснения процедуры, примеров и критериев разбора; hook — для привязки выбранной работы к событию.

Начните с одной задачи и одного проверяемого результата. Для ручного разбора файла достаточно навыка и /review-note путь; для проверки перед Edit или Write — небольшого PreToolUse-обработчика. Добавляйте следующую часть, когда можете назвать конкретное действие, которое первая часть не обеспечивает.