Как написать свой скилл для Claude: разбор структуры

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

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

Когда писать скилл, а когда хватит CLAUDE.md

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

Признаки, что пора писать скилл. Вы третий раз объясняете Claude одну и ту же последовательность действий: «возьми выгрузку, посчитай по каналам, сравни с прошлым месяцем, оформи по шаблону». Инструкция в CLAUDE.md разрослась до нескольких экранов и большую часть времени не нужна. Задача требует справочных материалов — шаблонов, примеров, спецификаций, — которые жалко держать в контексте постоянно. Или процедура рискованная, и вы хотите запускать её только сами, явной командой.

Обратный признак: если инструкция — одна-две строки и нужна в каждой сессии («тесты запускаются через make test»), скилл не нужен, это строчка в CLAUDE.md. Скилл ради одной фразы только добавляет описание в список, который Claude просматривает, и ничего не даёт взамен. Чем больше в списке бесполезных скиллов, тем труднее Claude выбрать нужный.

Где хранить скилл

Скилл — это папка с именем скилла, внутри которой лежит SKILL.md. От места хранения зависит, в каких сессиях он доступен и попадёт ли к коллегам.

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

Имя папки становится командой: скилл в папке weekly-report вызывается как /weekly-report. Если два скилла называются одинаково, действуют правила приоритета, поэтому имена лучше делать конкретными: не «report», а «ads-weekly-report».

Анатомия SKILL.md: поля и описание

Файл состоит из двух частей. Вверху между строками --- — служебные поля в формате YAML. Ниже — сами инструкции в обычном Markdown. Все поля необязательные, но одно документация прямо рекомендует заполнять всегда — описание.

Описание — самое важное в скилле. Claude видит описания всех доступных скиллов и по ним решает, какой подходит к задаче. Полный текст скилла он в этот момент не читает. Поэтому описание отвечает на два вопроса: что делает скилл и в каких ситуациях его применять. Документация советует ставить главный сценарий первым: описание вместе с полем when_to_use обрезается после 1536 знаков в общем списке.

Хорошее описание содержит слова, которыми люди реально формулируют задачу: «недельный отчёт», «сводка по рекламе», «сравнить каналы». Если Claude не вызывает скилл, когда должен, первым делом перепишите описание — в нём почти всегда не хватает формулировок, которыми задачу ставят на самом деле.

Первый скилл пошагово

Соберём скилл для еженедельного отчёта по рекламе — типичная задача маркетолога, которую каждый раз приходится объяснять заново. Шаг 1. Создайте папку .claude/skills/ads-weekly-report/ в проекте, где лежат выгрузки. Шаг 2. Создайте в ней файл SKILL.md с описанием и инструкцией.

Шаг 3. Положите рядом шаблон отчёта template.md. Шаг 4. Запустите командой /ads-weekly-report 2026-09-29 или просто попросите «сделай недельный отчёт по рекламе» — Claude найдёт скилл по описанию. Шаг 5. Посмотрите на результат и поправьте инструкцию там, где Claude сделал не так, как нужно. Обычно хватает двух-трёх итераций, после которых скилл стабильно выдаёт одинаковый результат.

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

Кто вызывает скилл и как передать аргументы

По умолчанию скилл может вызвать и Claude, и вы. Для части скиллов это неудобно. Процедуры с последствиями — деплой, отправка сообщений, коммит — лучше запускать только явной командой: для этого в описании ставится disable-model-invocation: true. Тогда описание даже не попадает в общий список, и Claude не запустит процедуру по собственной инициативе. Обратный случай — фоновые знания, которые не нужны как команда, например как устроена старая система учёта: для них user-invocable: false, и скилл исчезает из меню, оставаясь доступным Claude.

Аргументы. Всё, что вы пишете после имени скилла, подставляется в текст вместо $ARGUMENTS. Команда /fix-issue 123 превращает «исправь задачу $ARGUMENTS» в «исправь задачу 123». Если аргументов несколько, к ним можно обращаться по номерам: $ARGUMENTS[0], $ARGUMENTS[1], — или задать им имена в поле arguments. Подсказка в поле argument-hint покажется при вводе команды и напомнит, что передавать.

Разрешения. Поле allowed-tools позволяет Claude использовать перечисленные инструменты без запроса разрешения — но только в том шаге, где вызван скилл; со следующим вашим сообщением разрешение снимается. Разрешайте узко: не «Bash», а «Bash(git status *)». В организациях, где включены только корпоративные правила разрешений, это поле в личных и проектных скиллах игнорируется.

Вспомогательные файлы, скрипты и живые данные

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

Скрипты — сильная сторона скиллов. Вычисления, преобразования файлов, проверки лучше делать программой, которую Claude запускает, чем инструкцией «посчитай»: скрипт даёт одинаковый результат каждый раз. Агент поможет написать такой скрипт, а скилл закрепит его использование: в инструкции достаточно строки «запусти scripts/calc.py и используй его результат».

Живые данные в момент вызова. Конструкция !`команда` в тексте скилла выполняет команду до того, как Claude прочитает скилл, и подставляет её вывод. Например, строка !`git diff HEAD` подставит текущие изменения в репозитории, и Claude сразу получит их в задании, без лишнего шага. Так удобно подтягивать список файлов, вывод проверок, свежую выгрузку. Помните, что эти команды выполняются с вашими правами, — в скиллах из чужих источников проверяйте их перед установкой.

Как проверить и улучшать скилл

Проверьте две вещи по отдельности. Первая — вызов: попросите задачу пятью разными формулировками, как её сформулировали бы коллеги, и посмотрите, в скольких случаях Claude нашёл скилл сам. Если меньше чем в четырёх — дорабатывайте описание. Вторая — выполнение: прогоните скилл на 3 разных наборах данных, включая неудобный (пустой файл, лишняя колонка), и проверьте результат.

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

Перед тем как отдать скилл команде, прогоните его по короткому чек-листу. Его можно поручить и самому Claude: «проверь этот скилл по 7 пунктам и предложи правки».

Формат SKILL.md переносимый: те же скиллы понимают Codex от OpenAI и открытый агент OpenClaw, и многие скиллы работают в них без изменений. Если скилл получился удачным и полезен не только вам, его можно оформить как плагин и поделиться с командой или опубликовать. Подборки готовых скиллов по профессиям и задачам — в маркетплейсе скиллов, а о том, как сравниваются агенты, — в гайде Claude Code или Codex.

Автор: Артём Беспалов, маркетинговое ИИ-агентство «Термос Беспалова», Калининград.

Источники: документация Claude Code о скиллах: места хранения, поля SKILL.md, аргументы, вспомогательные файлы, динамический контекст (проверено 04.10.2026).