Как написать свой скилл: формат SKILL.md

Скилл - папка с файлом SKILL.md: вверху YAML-заголовок с именем и описанием, ниже инструкции в Markdown. Формат открытый, один и тот же скилл работает в Claude Code, Codex и других агентах.

Минимальный скилл

release-notes/
└── SKILL.md

---
name: release-notes
description: Пишет заметки к релизу по коммитам с прошлого тега. Использовать, когда просят changelog или release notes.
---

# Заметки к релизу

1. Найди последний тег: `git describe --tags --abbrev=0`.
2. Возьми коммиты после него: `git log <тег>..HEAD --oneline`.
3. Сгруппируй: новое, исправления, прочее.
4. Пиши коротко, без хэшей коммитов.

Поля заголовка

name - имя скилла. В Claude Code из него получается команда /release-notes, без поля берётся имя папки. Codex требует поле явно.

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

У Claude Code есть дополнительные поля: disable-model-invocation: true оставляет только ручной вызов, allowed-tools ограничивает инструменты, context: fork запускает скилл в отдельном подагенте. В списке скиллов описание обрезается до 1536 символов.

Как агент подключает скилл

В начале сессии агент получает только имена и описания скиллов. Полный текст SKILL.md загружается, когда задача совпала с описанием или когда скилл вызвали вручную: /имя в Claude Code, $имя в Codex. Поэтому установленные скиллы почти не занимают контекст, пока не нужны.

Дополнительные файлы

release-notes/
├── SKILL.md
├── references/
│   └── style.md
└── scripts/
    └── collect.sh

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

Codex дополнительно читает agents/openai.yaml: отображаемое имя, иконку, политику вызова и зависимости от инструментов.

Куда положить и как проверить

Для своего проекта - .claude/skills/ (Claude Code) и .agents/skills/ (Codex), для всех проектов - те же папки в домашнем каталоге. Подробно - в гайде как установить скилл. Заготовку создаёт команда npx skills init release-notes.

Как опубликовать

Выложите папку в публичный репозиторий на GitHub - её сразу можно ставить командой npx skills add owner/repo. Чтобы скилл попал в этот каталог, пришлите ссылку через форму: заявки проверяются вручную.