Навык (skill) в Claude Code — это папка с файлом SKILL.md: YAML-шапка с описанием, когда навык нужен, и обычный текст с инструкцией. Агент подключает навык сам, когда ваша задача совпадает с описанием, либо вы вызываете его вручную командой /имя-навыка. Плагин — это упаковка: каталог, который раздаёт сразу несколько навыков, подагентов, хуков и MCP-серверов и ставится одной командой из маркетплейса. Ниже — устройство обоих механизмов по официальной документации Anthropic, минимальный рабочий пример и граница, за которой навык заводить не нужно.

Что такое навык

Навык — это набор инструкций под конкретный вид работы, вынесенный из переписки в файл. В русскоязычных запросах его называют по-разному — «скилы», «скиллы», «навыки», — но механизм один, и отдельного вида навыков под каждое написание не существует.

Ключевое отличие от всего остального в конфигурации — момент загрузки. В контекст в начале сессии попадает только имя и описание навыка. Тело файла подгружается тогда, когда навык действительно вызван: вами через /имя или самим агентом, если описание совпало с задачей. Поэтому длинный справочник в навыке почти ничего не стоит, пока он не понадобился.

Из этого следует практическое правило: описание важнее тела. Именно по нему модель решает, подключать навык или нет. Описание должно содержать слова, которыми вы реально формулируете задачу, и главный сценарий — первым: связка description и when_to_use обрезается на 1536 символах в перечне навыков, и всё, что не поместилось, до модели не доедет.

Часть навыков в Claude Code встроена и доступна без настройки — среди них /code-review, /debug, /doctor, /loop, /run, /verify. Они устроены так же, как ваши собственные: это инструкции, а не зашитая логика. Отключаются целиком настройкой disableBundledSkills.

Навыки — не только про Claude Code. Формат SKILL.md следует открытому стандарту Agent Skills, который понимают и другие агенты. Claude Code добавляет к стандарту свои поля — управление тем, кто вызывает навык, запуск в подагенте, подстановку вывода команд. Если навык планируется переносить в другие инструменты, шапку стоит держать в пределах шести полей стандарта: name, description, license, compatibility, metadata, allowed-tools.

Навык, промпт, правила проекта и MCP

Четыре механизма постоянно путают, потому что все они «объясняют агенту, что делать». Разница — в том, когда содержимое попадает в контекст и кто решает, применять его.

МеханизмКогда загружаетсяДля чего
Промпт здесь и сейчас, один раз разовая задача; ничего не переживает конец сессии
CLAUDE.md и .claude/rules/ в начале каждой сессии (правила с полем paths — когда агент открывает подходящий файл) то, что верно всегда: команды сборки, соглашения, «всегда делай так»
Навык по требованию: при вызове /имя или при совпадении описания процедура из нескольких шагов и справочный материал, нужный иногда
MCP-сервер подключается на старте, схемы инструментов — по мере надобности доступ наружу: база, трекер, браузер, чужой API

Навык и MCP решают разные задачи и хорошо работают вместе: MCP даёт инструмент и соединение, навык — знание о том, как этим инструментом пользоваться в вашем проекте. Схема базы и типовые запросы к ней — это навык поверх MCP-сервера базы, а не второй MCP-сервер. Про сами серверы и их подключение — в статье про MCP в Claude Code.

Когда навык не нужен. Если инструкция помещается в одну строку и должна действовать всегда — это строка в CLAUDE.md, а не навык. «Пакетный менеджер — pnpm», «перед коммитом прогонять npm test», «хендлеры лежат в src/api/handlers/» — файл правил. Навык оправдан, когда набралась процедура: несколько шагов, порядок между ними, критерии остановки. Документация формулирует границу так же: раздел CLAUDE.md, выросший из факта в процедуру, пора переносить в навык, а сам CLAUDE.md держать в пределах 200 строк.

Если инструкция нужна только для одного каталога — есть промежуточный вариант: файл в .claude/rules/ с полем paths в шапке. Такое правило загружается, только когда агент работает с подходящими файлами, и не тратит контекст в остальное время.

Где живут навыки и как устроен файл

Место хранения определяет, кому навык доступен.

УровеньПутьОбласть действия
Пользовательский~/.claude/skills/имя/SKILL.mdвсе ваши проекты
Проектный.claude/skills/имя/SKILL.mdтолько этот проект, едет в репозиторий
Плагинныйплагин/skills/имя/SKILL.mdтам, где плагин включён
Организационныйкаталог управляемых настроеквсе пользователи организации

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

Имя команды берётся из имени каталога, а не из поля name в шапке: у пользовательских и проектных навыков name — это только подпись в списке. Старый формат .claude/commands/имя.md продолжает работать и даёт ту же команду; при совпадении имён выигрывает навык.

Правки подхватываются на лету: Claude Code следит за каталогами навыков и видит изменения в SKILL.md без перезапуска сессии. Если каталога не существовало на момент старта, сессию придётся перезапустить. Посмотреть, что вообще доступно, можно командой /skills; там же переключается видимость отдельных навыков, которая сохраняется в skillOverrides в настройках проекта.

Как написать свой навык

Минимальный навык — это каталог и один файл в нём. Пример: проверка перед выкладкой, которую вы каждый раз описываете руками.

mkdir -p .claude/skills/release-check

Дальше .claude/skills/release-check/SKILL.md:

---
description: Проверка перед выкладкой: тесты, миграции, changelog.
  Использовать, когда просят собрать релиз или выложить изменения на прод.
allowed-tools: Bash(npm test *) Bash(git status *)
disable-model-invocation: true
---

1. Прогнать `npm test` и показать вывод целиком, а не пересказ.
2. Проверить, что в `migrations/` нет неприменённых файлов.
3. Сверить CHANGELOG.md с историей коммитов от последнего тега.
4. Ничего не выкладывать самостоятельно: вернуть отчёт и остановиться.

Обязательных полей в шапке нет вообще, рекомендуется только description. Остальные поля из примера делают ровно две вещи:

  • disable-model-invocation: true — навык запускаете только вы. Это нужно всему, у чего есть побочные эффекты: деплой, коммит, отправка сообщений. Иначе агент однажды решит, что код выглядит готовым, и запустит выкладку сам. Побочный эффект — такой навык не занимает контекст, пока его не вызвали.
  • allowed-tools — перечисленные инструменты не будут спрашивать разрешения на том ходу, где навык вызван. Разрешение снимается с вашим следующим сообщением. Поле не ограничивает набор инструментов, а расширяет его; для обратного есть disallowed-tools.

Дальше навык растёт не за счёт длины SKILL.md, а за счёт соседних файлов. Тело навыка после вызова остаётся в контексте до конца сессии, поэтому каждая лишняя строка — постоянный расход; документация советует держать SKILL.md в пределах 500 строк, а подробности выносить.

.claude/skills/release-check/
├── SKILL.md      обязательный файл: шапка и инструкция
├── reference.md  длинный справочник, читается по ссылке из SKILL.md
└── scripts/
    └── check.sh  скрипт: агент его запускает, а не читает целиком

Три вещи, которые стоит знать сразу, чтобы не изобретать их заново:

  • Аргументы. Всё, что набрано после имени навыка, подставляется вместо $ARGUMENTS; отдельные аргументы доступны как $0, $1 и так далее.
  • Подстановка вывода команд. Строка вида !`git diff HEAD` в теле навыка выполняется до того, как модель увидит текст, и заменяется на вывод. Инструкция приходит уже с данными, а не с указанием их запросить.
  • Запуск в изолированном контексте. Поле context: fork отправляет навык в подагента: тело становится его заданием, история переписки ему не передаётся, в основную сессию возвращается результат. Подробнее про этот режим — в статье про подагентов Claude Code.

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

Плагины: что внутри и как ставятся

Плагин — это способ отдать свою настройку другим людям или перенести её в другой репозиторий. Технически это каталог, в корне которого лежат компоненты, а в подкаталоге .claude-plugin/ — манифест plugin.json с полями name, description, version.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      манифест плагина
├── skills/
│   └── review/SKILL.md  становится /my-plugin:review
├── agents/              описания подагентов
├── hooks/hooks.json     хуки
└── .mcp.json            MCP-серверы

Частая ошибка при сборке своего плагина: внутрь .claude-plugin/ кладут всё подряд. Туда идёт только plugin.json, остальные каталоги лежат в корне плагина.

Установка идёт из маркетплейса — каталога плагинов. Официальный маркетплейс Anthropic claude-plugins-official регистрируется сам при первом интерактивном запуске, остальные добавляются вручную:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install имя-плагина@claude-community

Команда /plugin без аргументов открывает панель с вкладками: обзор доступного, установленное, маркетплейсы и ошибки загрузки. Перед установкой там видно, что именно плагин добавит — команды, навыки, подагентов, хуки, MCP- и LSP-серверы — и оценку расхода контекста. Область установки выбирается из трёх: только для вас во всех проектах, для всех участников этого репозитория, или только для вас в этом репозитории. Если после установки написано Run /reload-plugins to activate — выполните эту команду, перезапуск не нужен.

Свой плагин удобно отлаживать без установки: claude --plugin-dir ./my-plugin подключает каталог на одну сессию, а claude plugin validate ./my-plugin проверяет структуру той же проверкой, которую проходят плагины при публикации в маркетплейс.

По запросу «claude code superpowers» ищут сторонний набор навыков Superpowers — методологию разработки поверх Claude Code с навыками под TDD, отладку, планирование и ревью. Он показателен как пример упаковки: один и тот же плагин раздаётся и через официальный маркетплейс, и через собственный маркетплейс автора, поэтому в разных инструкциях встречаются две разные команды установки — superpowers@claude-plugins-official и superpowers@superpowers-marketplace. Обе рабочие, актуальный список команд под каждый агент автор держит в README проекта.

Хуки: когда нужен не навык

Хук — это команда, которую Claude Code выполняет сам в определённой точке жизненного цикла. Настраиваются хуки не файлом навыка, а блоком hooks в settings.json (или файлом hooks/hooks.json внутри плагина); посмотреть настроенное можно командой /hooks.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run lint:fix" }]
      }
    ]
  }
}

Событий больше десятка: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact, SessionEnd и другие. Хук на PreToolUse умеет отменить вызов инструмента и объяснить модели причину.

Разница с навыком принципиальная, и она стоит того, чтобы её запомнить: навык — это просьба, хук — это гарантия. Навык агент читает и интерпретирует, результат может отличаться от раза к разу. Хук срабатывает на своём событии всегда, независимо от того, что решила модель, и ничего не стоит по контексту, пока не вернёт вывод. Поэтому запреты и защитные проверки — «не трогать .env», «не выполнять команду удаления» — пишут хуком, а не строкой в навыке или в файле правил. Полный список событий, формат входа и выхода и способы отладки — в официальной документации по хукам.

Безопасность чужих навыков и плагинов

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

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

Что имеет смысл открыть перед установкой чужого набора:

  • SKILL.md каждого навыка — целиком, включая шапку;
  • hooks/hooks.json — что и на каком событии выполняется автоматически;
  • .mcp.json — какие внешние серверы поднимутся и куда они ходят;
  • scripts/ и bin/ — код, который запускается, а не читается;
  • кто автор и как давно обновлялся плагин: панель /plugin показывает дату последнего обновления, а вкладка установленного — плагины, которыми вы давно не пользовались.

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

Чек-лист: заводить навык или нет

Прогоните задачу по восьми пунктам. Если на первых трёх ответ «нет» — навык не нужен.

  1. Это процедура, а не факт? Один шаг или одно соглашение — строка в CLAUDE.md. Несколько шагов с порядком между ними — навык.
  2. Вы объясняли это агенту третий раз? Повторяющаяся вставка в чат — главный признак того, что пора выносить в файл.
  3. Это нужно не всегда? Если нужно в каждой сессии — файл правил. Если иногда — навык, он и грузится только по требованию.
  4. Описание содержит ваши слова? Не «работа с релизами», а те формулировки, которыми вы ставите задачу. Главный сценарий — первым предложением.
  5. Есть побочные эффекты? Деплой, коммит, отправка наружу — disable-model-invocation: true, чтобы момент запуска выбирали вы.
  6. Тело короткое? Инструкция — в SKILL.md, справочники и примеры — в соседние файлы, скрипты — в scripts/.
  7. Это правило или запрет? Если условие должно выполняться всегда и без участия модели — это хук, а не навык.
  8. Нужно ли делиться? Один проект — .claude/skills/ в репозитории. Два и больше репозиториев или команда — плагин.

И обратная проверка, которую делают редко: раз в пару месяцев открывайте /skills и /plugin и удаляйте то, чем не пользуетесь. Описания всех навыков лежат в контексте каждый запрос, и когда их становится слишком много, Claude Code начинает обрезать описания — первыми у тех навыков, которые вызываются реже всего. Лишний набор не просто занимает место, он мешает сработать нужному.