Claude Code skills: что это и как написать свой

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

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

Простой способ понять: скилл - это регламент для агента.

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

Разница между объяснением в чате и скиллом в том, что скилл лежит в репозитории, версионируется вместе с кодом и работает одинаково у всех.

Из чего состоит скилл

Основа - файл с описанием, у которого есть две части.

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

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

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

Когда скилл лучше промпта

Три признака, что пора выносить объяснение в скилл:

1. Вы объясняете это в третий раз. Первый раз - нормально, второй - совпадение, третий - процедура.
2. Объяснение длиннее самой задачи. Если на постановку уходит больше текста, чем на результат, постановка должна жить отдельно.
3. Это делает не только один человек. То, что знает один разработчик и не знает второй, - главный источник расхождений.

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

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

Свой скилл по шагам

Возьмём реальную задачу: добавление новой статьи в блог на статическом сайте. Процедура повторяемая и в коде не описана.

Шаг 1. Опишите процедуру словами. Как вы делаете это руками: два файла на две локали с одинаковым слагом, обязательные поля во фронтматтере, сборка как проверка, ссылка на смежную статью.

Шаг 2. Сформулируйте, когда скилл применяется. «Когда нужно добавить или отредактировать статью в блоге либо в вики» - это годное описание. «Работа с контентом» - негодное, слишком широко.

Шаг 3. Запишите шаги по порядку и добавьте то, что легко забыть: какие поля обязательны, чего в тексте быть не должно, чем проверяется результат.

Шаг 4. Добавьте критерий готовности. Это важнее всего остального. «Сборка проходит и проверка ссылок не находит битых» - проверяемо. «Статья хорошая» - нет.

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

Частая ошибка

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

Общие советы модель и так знает. Ваш проект она не знает.

Что дальше

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