Скиллы в Claude Code: как научить агента своим процессам

Если вы работаете с Claude Code дольше пары недель, у вас наверняка накопился набор инструкций, которые вы раз за разом вставляете в чат: как оформлять коммиты, как выкатывать релиз, по какому чек-листу принимать вёрстку. Класть это в общий файл правил дорого: он загружается в каждую сессию целиком. Скиллы (skills) решают ровно эту проблему — это папка с инструкцией, которую агент подхватывает только тогда, когда она нужна.

Что такое скилл

Скилл — это каталог с файлом SKILL.md внутри. В файле два блока: YAML-фронтматтер (frontmatter — служебные поля между строками ---), который объясняет модели, когда брать этот скилл, и обычный markdown с инструкциями, которые модель выполняет, когда скилл сработал.

Вызвать скилл можно двумя способами: напечатать /имя-скилла вручную или просто описать задачу словами — Claude сам сопоставит запрос с описанием и подгрузит нужный скилл. Второе и есть главное отличие скиллов от простых заготовок промптов. Формат не привязан к одному инструменту: Claude Code следует открытому стандарту Agent Skills и добавляет поверх него свои расширения.

Важное изменение последних версий: пользовательские команды из .claude/commands/ слились со скиллами. Файл .claude/commands/deploy.md и скилл .claude/skills/deploy/SKILL.md одинаково дают команду /deploy. Старые файлы команд продолжают работать, но скиллы умеют больше: свою папку с вспомогательными файлами, управление тем, кто имеет право вызывать скилл, и автоматическую подгрузку моделью.

Почему это дешевле, чем правила в общем файле

Скиллы устроены по принципу постепенного раскрытия (progressive disclosure) — контекст расходуется в три уровня:

• Уровень 1 — метаданные. При старте сессии в контекст попадают только name и description каждого скилла, примерно по сотне токенов на штуку. Модель видит список того, что у неё есть.
• Уровень 2 — инструкции. Тело SKILL.md подгружается только в момент вызова.
• Уровень 3 — ресурсы. Вспомогательные файлы и скрипты в папке скилла не стоят ничего, пока агент их не откроет.

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

Первый скилл за пять минут

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

mkdir -p ~/.claude/skills/summarize-changes

Положите в него SKILL.md:

---
description: Разбирает незакоммиченные изменения и отмечает риски. Использовать, когда пользователь спрашивает, что изменилось, просит текст коммита или ревью диффа.
---

## Текущие изменения

!`git diff HEAD`

## Инструкции

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

Теперь фраза «что я тут наменял?» подтянет скилл сама, а /summarize-changes вызовет его явно. Имя команды берётся из названия каталога: в личных и проектных скиллах поле name задаёт только подпись в списке.

Где лежат скиллы

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

• Личные — ~/.claude/skills/<имя>/SKILL.md, работают во всех ваших проектах.
• Проектные — .claude/skills/<имя>/SKILL.md, коммитятся в репозиторий и достаются всей команде.
• Плагины — <плагин>/skills/<имя>/SKILL.md, работают там, где плагин включён.
• Корпоративные — раздаются через управляемые настройки на всю организацию.

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

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

Ещё деталь: Claude Code следит за папками скиллов и подхватывает правки без перезапуска. А вот новую папку верхнего уровня, созданную уже после старта сессии, он не увидит.

Фронтматтер: что можно настроить

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

• description — что делает скилл и когда его применять. Ключевой сценарий ставьте первым: описание в списке скиллов обрезается по длине.
• when_to_use — дополнительные фразы-триггеры и примеры запросов, дописываются к описанию.
• disable-model-invocation: true — вызывать может только человек. Обязательно для всего с побочными эффектами: деплой, отправка сообщений, коммит. Заодно убирает скилл из контекста модели совсем.
• user-invocable: false — наоборот: вызывает только модель. Для фоновых знаний вроде «как устроена наша легаси-система», которые не имеют смысла как команда.
• allowed-tools — инструменты, которые не будут спрашивать подтверждения на том ходу, где вызван скилл. Разрешение снимается со следующим вашим сообщением.
• disallowed-tools — наоборот, убирает инструменты из доступного пула, пока скилл активен.
• paths — glob-маски: скилл подгружается автоматически, только когда агент работает с подходящими файлами.
• model и effort — модель и уровень «усердия» на время работы скилла.
• context: fork и agent — выполнить скилл в изолированном сабагенте.

За пределами Claude Code — при загрузке скилла на claude.ai, через Skills API или при упаковке — допустимы только шесть полей стандарта: name, description, license, compatibility, metadata, allowed-tools. Лишнее поле не игнорируется, а роняет загрузку с ошибкой. Ограничения стандарта: name — до 64 символов, строчные буквы, цифры и дефисы; description — до 1024 символов.

Динамический контекст и аргументы

Конструкция !`команда` выполняется до того, как модель увидит текст скилла, и подставляет вывод команды прямо в инструкцию. Это не то, что запускает агент, — это препроцессинг, модель получает уже готовые данные. Если команда упадёт с ненулевым кодом, вызов скилла отменится целиком: агент не увидит ничего. Для команд, которые штатно возвращают ненулевой код, дописывайте || true.

Аргументы подставляются через $ARGUMENTS (всё, что напечатано после имени команды), $0, $1 — по позициям, либо по именам из поля arguments. Из служебных переменных чаще всего нужна ${CLAUDE_SKILL_DIR} — путь к папке самого скилла: с ней вложенный скрипт запускается одинаково независимо от текущего каталога.

Скилл в отдельном контексте

Поле context: fork отправляет скилл выполняться в сабагента: содержимое SKILL.md становится его промптом, история вашего диалога ему недоступна, результат прилетает обратно по готовности. Работает это только для скиллов с явной задачей — набор рекомендаций вроде «соблюдай такие-то соглашения» сабагент получит, но делать ему будет нечего.

Как понять, что скилл работает

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

Автоматизировать сравнение помогает официальный плагин skill-creator: он хранит тест-кейсы, запускает каждый в отдельном сабагенте, считает пройденные проверки, токены и время со скиллом и без, а также вслепую сравнивает две версии скилла.

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

Скиллы, сабагенты, MCP: что для чего

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

Частые ошибки

• Описание «для людей». «Полезный скилл для работы с релизами» модели ничего не даёт. Нужны глаголы и триггеры: что делает и по каким запросам применять.
• Раздутое тело. Загруженный скилл остаётся в контексте до конца сессии, так что каждая строка — повторяющийся расход. Держите SKILL.md компактным, справочники выносите в соседние файлы и ссылайтесь на них.
• Опасные действия без замка. Деплой, рассылка, коммит без disable-model-invocation — вопрос времени.
• Слепое доверие чужим скиллам. Скилл может выполнять код и выдавать себе широкие права через allowed-tools. Проверяйте вложенные файлы так же, как проверяли бы устанавливаемую программу.
• Ожидание, что личные скиллы доедут везде. Папка ~/.claude/skills/ на вашей машине не читается в Cowork и облачных сессиях. Для них скилл нужно включить для аккаунта claude.ai, закоммитить в репозиторий или упаковать в плагин.

Вывод

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