SKILL.md: поля frontmatter, структура папки скилла и пример для Claude

SKILL.md начинается с YAML-блока между двумя строками ---, после него идут инструкции в Markdown. Спецификация Agent Skills задаёт шесть полей: два обязательных и четыре по желанию.

Claude Code читает те же шесть полей и добавляет свои, например when_to_use, disable-model-invocation, context и paths. В Claude Code все поля необязательны: без name команда берёт имя папки, без description — первую непустую строку текста. При загрузке в claude.ai, через Skills API и при упаковке скриптом package_skill.py лишнее поле даёт ошибку, поэтому в переносимом скилле держитесь шести полей стандарта.

Claude API строже к name: в нём нельзя слова anthropic и claude и XML-теги. В description XML-теги тоже запрещены.

Скилл — папка, в которой обязателен только SKILL.md. Папки scripts/, references/ и assets/ спецификация советует как удобную раскладку, рядом можно класть любые другие файлы.

В scripts/ лежит код, который агент запускает. Набор языков зависит от агента, обычно это Python, Bash и JavaScript. В references/ — справка, которую агент читает при необходимости, в assets/ — шаблоны, картинки и таблицы данных.

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

roll-dice/
├── SKILL.md       # обязателен: поля и инструкции
├── scripts/       # код, который агент запускает
├── references/    # справка, агент читает её при необходимости
├── assets/        # шаблоны, картинки, таблицы данных
└── ...            # любые другие файлы и папки

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

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

Тело скилла Claude Code добавляет в диалог один раз и больше не перечитывает файл. После сжатия длинного диалога от каждого скилла остаются первые 5 000 токенов, на все скиллы вместе — 25 000. Важные правила держите в верхней части SKILL.md.

Скилл бросает кубик. Положите файл в .agents/skills/roll-dice/SKILL.md, для Claude Code — в .claude/skills/roll-dice/SKILL.md.

Имя папки roll-dice совпадает с полем name. В description сказано и что делает скилл, и на какие просьбы его включать. Чтобы проверить установку в Claude Code, спросите «What skills are available?» или вызовите скилл напрямую командой /roll-dice.

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

Чтобы бросить кубик, выполни команду. Она выдаёт случайное число
от 1 до числа граней:

```bash
echo $((RANDOM % <sides> + 1))
```

Вместо <sides> подставь число граней: 6 для обычного кубика, 20 для d20.

В заголовках карточек — текст ошибки, как его выводят валидаторы и загрузка в claude.ai.

У стандарта есть эталонная библиотека skills-ref на Python, она проверяет frontmatter и правила имени. Ставится из репозитория agentskills/agentskills, нужен Python 3.11 или новее.

Команде validate можно дать папку скилла или сам файл SKILL.md. Если ошибок нет, она печатает Valid skill, если есть — Validation failed и список ошибок с кодом выхода 1. Ещё две команды: skills-ref read-properties выводит поля в JSON, skills-ref to-prompt собирает XML-блок available_skills для системного промпта агента. Авторы предупреждают, что библиотека демонстрационная и для продакшена не предназначена.

В Claude Code 2.1.233 и новее скиллы с битым frontmatter находит команда claude plugin validate: claude plugin validate .claude/skills для скиллов проекта и claude plugin validate ~/.claude/skills для личных.

git clone https://github.com/agentskills/agentskills.git
cd agentskills/skills-ref
python -m venv .venv
source .venv/bin/activate
pip install -e .

skills-ref validate ./my-skill

skill-creator от Anthropic создаёт новые скиллы, правит готовые, прогоняет проверки и подбирает description, чтобы скилл включался на нужные просьбы. В Claude Code он ставится плагином.

Если Claude Code ответит, что маркетплейс claude-plugins-official не найден, добавьте его командой /plugin marketplace add anthropics/claude-plugins-official и повторите установку. Затем попросите, например: evaluate my summarize-changes skill with skill-creator. Тестовые запросы плагин хранит в evals/evals.json внутри папки скилла, а результаты прогонов со скиллом и без него сводит в benchmark.json.

/plugin install skill-creator@claude-plugins-official

Claude Code следит за папками скиллов: новый или исправленный SKILL.md подхватывается в текущей сессии без перезапуска. Если папку skills создали уже после запуска, выполните /reload-skills. Папку скилла не называйте synced: это имя Claude Code занял под скиллы, скачанные из claude.ai.

Готовые скиллы с командами установки для разных агентов собраны в каталоге /mcp/skills/.