К содержимому
Блог

Claude Code Skills: как создать навык для команды

Claude Code Skills: как создать навык для команды

Claude Code Skills помогают сохранить повторяемый порядок работы рядом с проектом: проверку перед релизом, правила для миграций, формат ревью или способ собирать отчёт. Вместо длинного промпта на каждую задачу команда описывает процедуру один раз в SKILL.md, а затем проверяет, что агент применяет её в нужный момент.

Коротко

  • Skill нужен для узкой повторяемой процедуры, которую можно проверить по результату.

  • Хороший description называет ситуацию запуска, а тело задаёт шаги, границы и критерий остановки.

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

Что решают Claude Code Skills

Агенту часто не хватает не знаний языка, а местных договорённостей. В одном репозитории перед изменением схемы нужен снимок базы, в другом запрещены массовые замены, в третьем PR нельзя открыть без конкретного набора проверок. Такие правила неудобно каждый раз вставлять в запрос.

Skill хранит именно процедуру. Он не заменяет документацию проекта и не пытается описать весь продукт. Если правило важно при каждой задаче, ему место в файле инструкций проекта. Если правило включается только для ревью, выпуска или импорта данных, отдельный skill держит основной контекст короче.

Начните с наблюдения. Если за месяц команда трижды вручную объясняла агенту одинаковую последовательность, это кандидат на skill. Если задача меняется каждый раз и критерий успеха расплывчат, сначала проясните процесс, а файл появится позже.

Чем skill отличается от MCP и отдельного агента

Эти механизмы легко смешать, хотя они отвечают на разные вопросы.

МеханизмЧто добавляетКогда выбирать
SkillИнструкцию и порядок действийПроцедура повторяется и не требует нового доступа
MCPИнструмент или данные из внешней системыАгенту нужен трекер, база, браузер или другой сервис
Отдельный агентИзолированный контекст для отдельной работыЗадача большая, шумная или независима от основной

Например, skill для выпуска может потребовать данные из трекера через MCP и поручить проверку независимому агенту. Но сам skill остаётся текстом процесса. Он не открывает доступы сам по себе.

Для настройки Claude Code под Relay сначала откройте страницу интеграции, а команды клиента держите в отдельной памятке по CLI. Об устройстве доступных моделей рассказывает каталог.

Как написать первый SKILL.md

Полезный первый skill лучше сделать маленьким. Возьмём проверку описания pull request перед отправкой на ревью. Её результат понятен: есть краткое описание, шаги проверки и список рисков либо явное сообщение, что рисков не найдено.

Создайте папку, которую использует ваша установка Claude Code, и файл SKILL.md. Путь и способ установки меняются между версиями клиента, поэтому сверяйте их с официальной инструкцией клиента. В самом файле держите два слоя: короткие метаданные и рабочие шаги.

markdown
---
name: pr-summary
description: 'Use when the user asks to prepare a pull request description or summarize changes for review.'
---

## Goal

Give a reviewer the purpose of the change and a reproducible check.

## Steps

1. Read the diff against the target branch.
2. Group changes by user-visible effect, not by filename.
3. State one risk that remains, or write that no specific risk was found.
4. Add commands that a reviewer can run without access to secrets.

## Stop condition

Do not invent a ticket number, test result, release date, or deployment status.

Здесь важнее всего description. Он описывает не тему файла, а момент применения. «Помощник для PR» слишком широко. Формулировка с реальными словами пользователя связывает skill с задачей, которую агент получит в чате.

Тело не должно превращаться в корпоративный манифест. Пишите команды, границы, исключения и ожидаемый результат. Фраза «пиши качественно» ничего не проверяет. Фраза «не называй тест пройденным, пока команда не завершилась с кодом 0» задаёт наблюдаемое действие.

Как добавить ресурсы и не засорить контекст

У skill часто есть дополнительные материалы: шаблон описания, перечень проверок, короткий скрипт или таблица миграций. Держите их рядом и ссылайтесь на конкретный файл из SKILL.md. Не копируйте один и тот же список в каждый skill.

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

Скрипт в папке skill не делает его безопасным автоматически. Перед установкой прочитайте текст, посмотрите, какие команды он предлагает, какие файлы меняет и нужен ли ему сетевой доступ. Это обычная зависимость с правом влиять на работу агента.

Как проверить, что skill срабатывает

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

Проверьте четыре вещи:

  1. Агент выбрал skill до начала действий.

  2. Он выполнил обязательные шаги в правильном порядке.

  3. Он остановился на запрете, а не обошёл его удобным предположением.

  4. Результат можно проверить без знания внутреннего хода рассуждений.

Если skill не включился, сначала перепишите description под настоящую формулировку задачи. Если включился, но дал слабый результат, сократите общие слова и добавьте недостающий критерий. Не пытайтесь лечить проблему ещё пятью страницами инструкций.

Какие навыки стоит написать первыми

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

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

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

Когда skill пора переписать

Сигналов обычно три. Первый: агент регулярно спрашивает то, что skill уже должен был объяснить. Второй: шаги противоречат актуальному инструменту. Третий: файл срабатывает там, где не нужен. В первом случае уточняют текст, во втором обновляют факт, в третьем сужают description.

Не правьте документ по памяти после неудачной сессии. Сначала найдите, где именно агент свернул с процедуры: не выбрал skill, пропустил шаг, понял правило иначе или упёрся в внешний блокер. Одна причина, один небольшой патч. Тогда очередное изменение не создаст новую неоднозначность.

Как поддерживать набор skills

Проектные skills живут вместе с кодом и меняются тем же pull request, который меняет процесс. Поменялась команда миграции, значит, проверяют и файл с инструкцией. Иначе следующий запуск добросовестно повторит уже неверный порядок.

Раз в несколько недель откройте список skills и задайте к каждому три вопроса: для какой задачи он реально срабатывал, какое правило в нём ещё нельзя вывести из репозитория, кто отвечает за обновление. Пустой ответ означает, что файл пора сократить, объединить с соседним или удалить.

Skill нужен для каждого типа задачи?

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

Можно ли положить в skill секрет или ключ API?

Нет. Skill попадает в контекст агента, а файл проекта может попасть в историю Git. Секрет хранится в механизме секретов или переменной процесса. В инструкции достаточно назвать переменную и указать, где её задать.

Когда вместо skill нужен MCP-сервер?

MCP выбирают, когда агенту нужен инструмент или свежие данные, которых нет в рабочем дереве: карточка задачи, запись в базе, доступ к браузеру. Skill может объяснить порядок использования такого инструмента, но не заменяет сам доступ.

Создать аккаунт Relay

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.