Как написать SKILL.md: шесть полей стандарта и пример

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

Скилл — папка. Имя папки совпадает с полем name. Внутри:

my-skill/
  SKILL.md          инструкция с frontmatter
  scripts/          код, который агент запускает
  references/       справка, которую агент читает по необходимости
  assets/           шаблоны, картинки, данные

Стандарт описан на agentskills.io. Изначально его разработала Anthropic, сейчас формат читают Claude Code, claude.ai и API Claude, Codex, Cursor, GitHub Copilot, Gemini CLI, Kiro, OpenCode, Zed и Windsurf (в документации он теперь Devin Desktop). Репозиторий спецификации agentskills/agentskills на 24.10.2026 собрал 26 552 звезды, лицензия Apache-2.0.

Шесть полей спецификации

У claude.ai и API Claude правила жёстче: имя не может содержать слова anthropic и claude и XML-теги, а любое поле сверх этих шести даёт ошибку загрузки. Copilot молча не грузит скилл с невалидным именем. Проверить файл до публикации можно валидатором из спецификации: skills-ref validate ./my-skill.

Пример SKILL.md

Набросок для иллюстрации, не реальный скилл из каталога:

---
name: release-notes
description: Пишет заметки к релизу по git log между двумя тегами. Использовать, когда просят changelog, release notes или список изменений версии.
license: MIT
metadata:
  author: your-team
  version: "1.0"
---

# Release notes

1. Найди два последних тега: git tag --sort=-creatordate | head -2
2. Собери коммиты между ними: git log --oneline A..B
3. Сгруппируй по Added / Changed / Fixed. Шаблон в references/template.md.
4. Не выдумывай пункты, которых нет в логе.

Обратите внимание на description. Первая фраза говорит, что скилл делает, вторая перечисляет слова, по которым агент поймёт, что пора его включить. Агент решает только по этому полю, тело он ещё не видел.

Progressive disclosure: почему важны размеры

Скиллы грузятся в три шага. На старте в контекст попадают только имя и описание всех скиллов, около 100 токенов на каждый. Когда скилл активирован, читается тело SKILL.md. Файлы из references/ и scripts/ агент открывает, только если тело на них сослалось.

Отсюда лимиты из спецификации: тело лучше держать короче 5 000 токенов и 500 строк, а ссылки на файлы делать на один уровень вглубь. Справку на 2 000 строк кладите в references/ и ссылайтесь на неё из SKILL.md.

Есть и лимит на список. В Claude Code весь список скиллов занимает до 1 % контекстного окна, а description вместе с when_to_use обрезается до 1 536 символов. В Codex на список отведено 2 % окна или 8 000 символов. При нехватке места описания укорачиваются, поэтому главное пишите в начале description.

Расширения платформ и как остаться совместимым

Каждая платформа добавила свои поля:

• Claude Code: when_to_use, argument-hint, disable-model-invocation, user-invocable, model, effort, context: fork, paths, hooks и другие. Поля license, compatibility и metadata он принимает, но не использует.
• Codex: отдельный файл agents/openai.yaml с метаданными интерфейса и политикой неявного вызова.
• Cursor: disable-model-invocation, icon, color, устаревшее paths.
• Copilot: argument-hint, user-invocable, disable-model-invocation, экспериментальное context: fork.

Наша позиция: если скилл публичный, оставьте во frontmatter только шесть полей стандарта. Тогда он загрузится везде, включая строгий claude.ai. Платформенные поля имеют смысл в приватном скилле под одного агента.

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

• Имя папки и name совпадают, в имени нет заглавных букв.
• Description отвечает на два вопроса: что делает и когда включать.
• Скрипты не ходят в сеть без нужды и не читают файлы вне проекта. GitHub прямо предупреждает, что чужие скиллы никто не проверяет.
• В папке есть LICENSE. Без лицензии ваш скилл нельзя законно копировать, и каталоги вроде нашего покажут его только ссылкой.

Как поставить готовый скилл, описано в гайдах для Claude Code, Codex и Cursor. Образцы для изучения — в каталоге скиллов.