Skill Claude Code: как устроен навык и когда его писать

Что это решает

Skill в Claude Code — папка с файлом SKILL.md, куда складывают инструкцию, которую иначе диктуют заново каждую сессию: как выкатывать, как оформлять тикет, каким SQL можно ходить в боевую базу. Без навыков такая инструкция живёт либо в голове, либо в CLAUDE.md, который читается целиком при каждом запуске и со временем превращается в свалку, где агент перестаёт различать главное. Навык подгружается только тогда, когда задача совпала с его описанием, поэтому двадцать навыков не стоят двадцати простыней в стартовом контексте. Заодно снимается разнобой в команде: правила лежат в репозитории и приезжают всем по git pull.

Как устроено

Файл навыка

Минимальный навык — одна папка и один файл внутри неё:

.claude/skills/release-checklist/SKILL.md

Имя папки работает идентификатором. Внутри файла два блока — YAML-шапка и тело.

---
name: release-checklist
description: Прогон релизного чеклиста перед выкатом — сборка, миграции, план отката. Использовать, когда просят «выкатить», «собрать релиз», «задеплоить на прод», а также перед созданием тега.
---

# Релизный чеклист

## 1. Перед сборкой
- `make test` — прогон обязателен, красный тест останавливает выкат
- миграции: просмотреть `database/migrations`, для каждой новой описать откат

## 2. Сборка
- только таргеты из `Makefile`, свои команды не изобретать

Обязательных полей в шапке два: name и description. Имя совпадает с именем папки. Тело — обычный markdown: заголовки, списки, таблицы, куски команд. Агент читает его как инструкцию к исполнению, а не как справку «на почитать», поэтому формулировки в теле пишут глаголами: «прогнать», «проверить», «не трогать».

Что попадает в контекст и в какой момент

В стартовый контекст сессии попадают только name и description каждого доступного навыка — по паре строк на штуку. Тело SKILL.md читается в тот момент, когда навык вызван: сработало совпадение с описанием либо человек попросил напрямую. Отсюда следует главное правило написания: description отвечает на вопрос «когда меня применять», тело — на вопрос «что делать».

Описание — единственный крючок

Навык, который не сработал, ведёт себя ровно как ненаписанный, и ошибка при этом не видна: агент просто делает по-своему. Поэтому описание пишут через триггеры.

Слабое описание:

description: Работа с релизами.

Рабочее описание перечисляет: с какими формулировками приходит человек, какие файлы и команды в деле, какие форматы данных, и когда навык применять не надо.

description: Выкат приложения на прод и на dev-стенд через Makefile. Использовать при просьбах «задеплоить», «выкатить», «поднять стенд», при работе с .gitlab-ci.yml и Makefile, перед созданием тега. Не использовать для правки кода без выката.

Описание читает машина, а не человек, — экономить слова тут нечем. Длинное точное описание срабатывает, короткое красивое молчит.

Три места, где лежат навыки

Проектный уровень — рабочая лошадка. Файл лежит в git рядом с кодом, проходит ревью в MR и обновляется вместе с процессом, который описывает. Личный уровень годится для привычек одного человека: формат заметок, любимая раскладка отчёта.

Приложенные материалы

Рядом с SKILL.md кладут подпапки: references/ для длинных справок, scripts/ для готовых скриптов, assets/ для шаблонов. Ссылку дают относительным путём и обязательно с условием, когда файл открывать:

Полный перечень полей ответа — в `references/api-fields.md`, открывать только при разборе ошибки 422.
Шаблон отчёта — `assets/report.md`, копировать целиком, поля не переименовывать.

Так тело SKILL.md остаётся коротким, а тяжёлые куски подтягиваются по необходимости. Навык на двести строк со всеми справками внутри работает хуже, чем навык на тридцать строк с четырьмя ссылками.

Чего навык не делает

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

Как подключить

1. Создать папку в репозитории проекта:

mkdir -p .claude/skills/sql-prod

2. Написать файл навыка:

cat > .claude/skills/sql-prod/SKILL.md <<'EOF'
---
name: sql-prod
description: Правила запросов к боевой базе. Использовать при любых просьбах посчитать метрику, выгрузить данные, проверить цифру по базе, а также при словах SELECT, запрос, выгрузка, отчёт по базе.
---

# Запросы к боевой базе

1. Только `SELECT` и `WITH`. Любая правка данных — стоп и вопрос владельцу.
2. `LIMIT` обязателен во всех запросах без исключения.
3. Персональные данные (почта, телефон) не выводить без явной просьбы.
4. Имена таблиц брать из `data/schema_compact.md`, не по памяти.
EOF

3. Сверить шапку: name совпадает с именем папки, description содержит формулировки, с которыми реально приходят.
4. Перезапустить сессию — список доступных навыков собирается при старте.
5. Проверить срабатывание: задать вопрос словами из описания и посмотреть, идёт ли агент по шагам из тела.
6. Закоммитить .claude/skills/ вместе с кодом, чтобы навык уехал команде.
7. Всё, что длиннее экрана, вынести в references/ и сослаться из тела.

Полезные сценарии

• Релизный чеклист: сборка, миграции, план отката, порядок выката через Makefile.
• Правила похода в боевую базу: только чтение, обязательный LIMIT, список запрещённых таблиц.
• Формат тикета в трекере: какие поля заполнять, какой текст в описании, куда двигать карточку.
• Разбор падений конкретного сервиса: где логи, какие грепы, три самые частые причины.
• Стиль код-ревью команды: что блокер, что комментарий, что игнорируется.
• Онбординг в модуль: карта каталогов, точки входа, что трогать нельзя.
• Формат письма клиенту: тон, подпись, чего не обещать.

Ограничения

• Слабое описание = мёртвый навык, и провал молчаливый: агент не сообщает, что мимо него прошла подходящая задача.
• Тело навыка занимает контекст текущей сессии — навыки не изолированы в отдельном окне, в отличие от субагентов.
• Несколько больших навыков с пересекающимися описаниями конкурируют между собой, и выбирается не тот.
• Навык не гарантирует исполнение. Это инструкция, которой модель следует, а не проверка на выходе; жёсткие запреты ставят хуками и правами.
• Личные навыки из ~/.claude/skills не видит никто, кроме владельца машины. Для команды путь один — репозиторий.
• Навык не следит за собственной актуальностью: процесс поменялся — файл правят руками, иначе агент уверенно работает по устаревшему.
• Секреты в теле навыка утекают вместе с репозиторием. Ключи и адреса продовых хостов туда не кладут.

Как проверить результат

• Открыть новую сессию и задать вопрос словами из description. Сработавший навык виден по тому, что агент выполняет конкретные шаги из тела файла вместо общих рассуждений.
• Вставить в тело маркер — редкое требование вроде «в конце вывести строку CHECKLIST-OK» — и посмотреть, появилось ли оно. Появилось, значит файл прочитан целиком.
• Проверить на коллеге после git pull: проектный навык должен работать без дополнительной настройки на его машине.
• Задать запрос, который под описание подходить не должен, и убедиться, что навык не вызвался. Слишком широкое описание тянет навык в чужие задачи и мешает.
• Прогнать реальную задачу до конца и сверить итог с тем, что написано в теле: расхождение означает, что инструкция устарела или сформулирована так, что допускает второе толкование.

Правило одной строкой: навык заводят на инструкцию, которую пришлось повторить в третий раз, и описывают по признаку «когда применять», а не «что умеет».