Как написать свой скилл для AI-агента

Если ваш скилл не срабатывает, спросите в комментариях моего канале SkillFoxx в Telegram. Там же я отмечаю хорошие новые скиллы, на которых удобно учиться.

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

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

По спецификации Agent Skills скилл — это папка, в которой обязателен один файл SKILL.md. Рядом кладут папки scripts, references и assets для кода, справочников и шаблонов. Файл начинается с блока YAML между строками ---, в нем два обязательных поля.

• name до 64 символов: строчные латинские буквы, цифры и дефис, без двух дефисов подряд. Имя совпадает с именем папки.
• description до 1024 символов: что делает скилл и в каких случаях его вызывать.

Необязательные поля license, compatibility и metadata указывают лицензию, требования к окружению и данные автора, а поле allowed-tools спецификация пока помечает как экспериментальное.

Пример SKILL.md

Скилл ниже проверяет заметки к релизу. Его можно скопировать в .claude/skills/release-notes/SKILL.md и попробовать.

---
name: release-notes
description: Проверяет и дописывает заметки к релизу в CHANGELOG.md. Используй, когда пользователь просит подготовить релиз, обновить changelog или описать изменения версии. Не используй для коммит-сообщений.
---
# Заметки к релизу
1. Прочитай git log от последнего тега до HEAD.
2. Сгруппируй изменения: новое, исправлено, удалено.
3. Каждый пункт пиши одной строкой с глаголом в прошедшем времени.
4. Сверь номер версии с package.json. Если они расходятся, остановись и спроси.
5. Покажи черновик и жди подтверждения, прежде чем писать в CHANGELOG.md.

В описании есть триггеры («подготовить релиз», «обновить changelog») и граница, когда скилл не нужен. Шаги короткие, каждый дает проверяемый результат. Пятый шаг держит запись в файл под контролем человека.

Как написать описание, которое агент найдет

Агент видит только поле description, пока не решил открыть скилл. По спецификации на старте в контекст попадают имя и описание всех скиллов, около 100 токенов на каждый. Claude Code к тому же обрезает описание вместе с полем when_to_use до 1536 символов, поэтому главный сценарий ставьте в начало.

Сравните два описания. «Помогает с документами» подходит к любому скиллу, и агент не свяжет его с задачей. «Извлекает текст и таблицы из PDF, заполняет формы, склеивает файлы. Используй, когда пользователь упоминает PDF или формы» дает агенту слова, которые встретятся в просьбе. Второй пример взят из спецификации Agent Skills.

Сколько писать в самом SKILL.md

Спецификация советует держать тело SKILL.md короче 5000 токенов и 500 строк. Все, что длиннее, выносят в references и ставят ссылку из текста. Агент открывает такие файлы, только когда они нужны. Так же устроены официальные скиллы Anthropic для docx, pdf, pptx и xlsx (179 тыс. ★ репозитория): короткий SKILL.md и справочники со скриптами рядом.

Если шаг проще сделать программой, например посчитать токены или проверить JSON, кладите скрипт в scripts и пишите в SKILL.md точную команду запуска. Подсчет токенов скрипт выполнит одинаково при каждом запуске, а модель по словесному описанию может ошибиться в числе. Но скилл со скриптом получает более высокий уровень риска, потому что запускает код на машине пользователя.

Куда положить скилл для каждого агента

• Claude Code читает .claude/skills/<имя> в проекте и ~/.claude/skills/<имя> для пользователя.
• Cursor читает .agents/skills и .cursor/skills в проекте, ~/.agents/skills и ~/.cursor/skills для пользователя.
• Codex читает .agents/skills от текущей папки до корня репозитория и ~/.agents/skills для пользователя.

Пути взяты из документации Claude Code, Cursor и Codex на 30 сентября 2026 года. Удобно держать скилл в .agents/skills и ставить на него символическую ссылку из .claude/skills, тогда один файл читают все три агента. Установщик SkillFoxx раскладывает скиллы по этой же схеме. Про Codex подробнее в статье Codex CLI: скиллы, MCP и с чего начать.

Как проверить скилл перед публикацией

Первая проверка — формат. Вставьте текст файла в валидатор SKILL.md на нашем сайте, он покажет ошибки в имени и описании. Проверка идет в браузере, текст на сервер не уходит.

Вторая проверка — поведение. Откройте новую сессию агента, попросите сделать задачу своими словами, не называя скилл, и посмотрите, откроет ли агент SKILL.md. Если нет, в описании не хватает слов, которыми вы формулируете задачу.

Скилл, который делает что-то необратимое, лучше закрыть от автоматического вызова. В Claude Code для этого есть поле disable-model-invocation: true, тогда скилл запускается только командой /release-notes.

Готовые скиллы как образец

Прежде чем писать свой, откройте два-три готовых. В каталоге SkillFoxx 695 скиллов, у 244 из них низкий риск, то есть внутри только инструкции и справочники. Их удобно читать как образец структуры.

• Скиллы Мэтта Покока для инженеров, 272 тыс. ★ репозитория. Набор небольших скиллов для TDD, отладки и ревью, каждый решает одну задачу.
• Skill Creator, 2,3 тыс. ★ репозитория. Скилл, который проводит агента через создание нового скилла по спецификации и проверяет метаданные скриптом на Python.
• В официальном репозитории Anthropic есть свой skill-creator и пустой шаблон template/SKILL.md.

Готовый скилл можно предложить в каталог через форму на сайте: мы выставим уровень риска по той же шкале и добавим команду установки для Claude Code, Cursor и Codex.