Claude Code skills: как устроены навыки, SKILL.md и когда агент их подгружает

Что такое skills в Claude Code

Skill (навык) — это папка с файлом SKILL.md, в котором записана инструкция для конкретного типа задач: как деплоить проект, как проводить ревью, как выпускать релиз. Агент знает о существовании навыка с начала сессии, но читает его целиком только тогда, когда задача действительно этого требует.

Claude Code skills решают проблему, знакомую всем, кто долго ведёт CLAUDE.md: файл инструкций разрастается. Процедура деплоя на 80 строк нужна раз в неделю, но в файле она занимает место в контексте каждой сессии — в том числе при правке опечатки в README. Навык выносит такие процедуры из постоянного контекста и подключает их по требованию.

Из чего состоит навык

Минимальный навык — одна папка и один файл. Проектные навыки лежат в репозитории, личные — в домашнем каталоге пользователя:

.claude/skills/deploy/SKILL.md      # навык проекта, общий для команды через git
~/.claude/skills/review/SKILL.md    # личный навык, доступен во всех проектах

Рядом с SKILL.md можно положить вспомогательные файлы: шаблоны, скрипты, справочники. Агент откроет их, только если основной текст навыка на них сошлётся и они понадобятся:

.claude/skills/deploy/
├── SKILL.md           # главная инструкция
├── checklist.md       # подробный чек-лист, читается по ссылке
└── rollback.sh        # скрипт отката

Frontmatter: name и description

Файл начинается с блока YAML между строками ---. Два поля важнее всех остальных: name — короткое имя навыка, и description — описание того, что навык делает и когда его применять.

---
name: deploy
description: Деплой сайта на хостинг по FTP. Использовать, когда нужно залить изменения на сервер, проверить расхождения с сервером или откатить деплой.
---

# Деплой

1. Сначала пробный прогон: `./deploy.sh -n`.
2. Проверить список файлов: в нём не должно быть секретов и тестовых скриптов.
3. Залить: `./deploy.sh`.
4. Открыть изменённые страницы и убедиться, что они отдают 200.

Откат — см. rollback.sh в этой папке.

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

Когда агент подгружает навык

В начале сессии в контекст попадают только имя и описание каждого доступного навыка. Это несколько строк на навык, поэтому их можно держать десятки. Когда запрос пользователя или текущий шаг работы совпадает с описанием, агент вызывает навык — и только тогда в контекст загружается полный текст SKILL.md.

Из этого следует главное практическое правило: навык срабатывает по описанию. Агент не видит тела навыка, пока не решил его открыть. Если в description написано «Вспомогательный навык», агент не поймёт, когда он нужен. Если написано «Деплой на хостинг; использовать, когда нужно залить изменения на сервер или откатить деплой» — поймёт.

Кроме автоматического выбора, навык можно вызвать явно — по имени через слеш, например /deploy. Это удобно, когда вы точно знаете, какая процедура нужна, и не хотите полагаться на то, что агент сам сопоставит запрос с описанием.

Как писать description, чтобы навык срабатывал

• Что делает — одной фразой, глаголом: «Деплой сайта», «Ревью изменений перед коммитом».
• Когда использовать — перечислите формулировки, которыми пользователь реально просит эту задачу: «залей на сервер», «выложи», «откати».
• Когда не использовать, если навык легко спутать с соседним: «не для деплоя бота, только сайта».
• Без общих слов вроде «полезный навык» и «помогает в работе» — они не несут сигнала.

Прогрессивное раскрытие

Навыки построены на принципе прогрессивного раскрытия (progressive disclosure): информация подаётся слоями, и каждый следующий слой загружается, только когда нужен.

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

Skills, CLAUDE.md и slash-команды: в чём разница

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

Практическое правило выбора простое. Если инструкция нужна почти в каждой задаче — ей место в CLAUDE.md. Если она нужна в задачах определённого типа — это навык. Если вы сами каждый раз набираете один и тот же длинный запрос — это кандидат в команду или в навык, который вызывается вручную.

Жёсткие запреты в навык не переносите. Навык может и не загрузиться, а правило «никогда не коммитить секреты» должно действовать всегда. Такие инварианты остаются в CLAUDE.md и по возможности подкрепляются механикой: хуками, правами доступа, проверками в CI.

Как создать skill для Claude Code: пошагово

1. Найдите повторяющуюся процедуру. Хороший признак — вы уже трижды объясняли агенту одно и то же или в CLAUDE.md есть раздел, который нужен в одной задаче из десяти.
2. Создайте папку .claude/skills/<имя>/ и файл SKILL.md внутри.
3. Напишите frontmatter с name и description, где явно сказано, когда навык применять.
4. Опишите шаги конкретными командами и критериями готовности: что проверить, какой результат считать успехом.
5. Вынесите длинное в соседние файлы и сошлитесь на них из основного текста.
6. Уберите дубль из CLAUDE.md, оставив одну строку-указатель: «Деплой — навык deploy».
7. Проверьте: в новой сессии попросите задачу своими словами, без названия навыка, и посмотрите, подхватил ли его агент. Если нет — переписывайте описание.

Примеры навыков

Навык деплоя

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

Навык ревью

---
name: review
description: Ревью текущих изменений перед коммитом. Использовать, когда просят проверить diff, найти ошибки в правках или подготовить изменения к коммиту.
---

# Ревью изменений

1. Получить diff: `git diff` и `git diff --staged`.
2. Для каждого изменённого файла проверить:
   - пользовательский ввод экранируется при выводе;
   - SQL-запросы параметризованы;
   - нет отладочного вывода и временных файлов.
3. Запустить тесты и линтер проекта (команды — в CLAUDE.md).
4. Отчёт: список проблем с файлом и строкой, от серьёзных к мелким.
   Если проблем нет — так и написать, без выдуманных замечаний.

Такой навык превращает «посмотри, всё ли нормально» в воспроизводимую проверку с одинаковым набором пунктов от раза к разу.

Навык завершения сессии

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

Типичные ошибки

• Размытое описание. Навык есть, но агент его не вызывает. Лечится переписыванием description с конкретными триггерами.
• Навык-простыня. В SKILL.md перенесли весь старый раздел на 400 строк. Проблема раздутого контекста вернулась, только позже. Держите основной текст коротким, детали — в соседних файлах.
• Дублирование с CLAUDE.md. Одна и та же процедура описана в двух местах и со временем расходится. Источник правды должен быть один.
• Пересекающиеся навыки. Два навыка с похожими описаниями — агент выбирает между ними случайно. Разведите их явными «использовать / не использовать».
• Устаревшие команды. Скрипт переименовали, а навык ссылается на старый. Навык — часть кода проекта: правьте его в том же коммите, что и процедуру.

Как понять, что пора выносить раздел в навык

Полезно периодически пройтись по CLAUDE.md и для каждого раздела спросить: в какой доле обычных задач он действительно нужен? Если раздел нужен почти всегда — он на своём месте. Если в одной задаче из десяти — это кандидат в навык.

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

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

Итог

Claude Code skills — способ хранить процедуры рядом с проектом и не платить за них контекстом в каждой сессии. Описание навыка видно всегда, тело загружается по необходимости, вспомогательные файлы — ещё позже. В CLAUDE.md остаются карта проекта и жёсткие правила, в навыки уходят деплой, ревью, релизы и прочие задачи определённого типа. Устройство файлов инструкций и прогрессивное раскрытие контекста разобраны на практике в курсе по harness engineering.