раздел 05 · подстраница 1

Анатомия skill: SKILL.md и frontmatter

Skill - это упакованный процесс, который Claude может подцепить как готовый рецепт. Один файл SKILL.md с YAML-frontmatter и Markdown-инструкциями. Никакого Python, никакого билда - просто текст.

Зачем

Если вы делаете одно и то же чаще двух раз - заворачивайте в skill. Деплой, ревью PR, генерация changelog, постинг в Telegram - всё это типовые процессы. Skill превращает их в вызываемые /skill-name юниты, которые сами подгружают нужные инструменты и контекст.

Отличие от обычного промпта: skill хранится в файловой системе, версионируется в git, разделяется между проектами и подключается автоматически по описанию.

Где лежит SKILL.md

Два уровня:

  • ~/.claude/skills/<name>/SKILL.md - глобально, доступен во всех проектах.
  • .claude/skills/<name>/SKILL.md - в проекте, едет в git, виден коллегам.

Имя директории = имя skill = строка после / при вызове. Например ~/.claude/skills/blog-post-writer/SKILL.md -> вызов /blog-post-writer.

mkdir -p ~/.claude/skills/deploy
$EDITOR ~/.claude/skills/deploy/SKILL.md

Структура файла

---
name: deploy
description: Деплой текущего проекта через git push на сервер. Использовать когда пользователь говорит "задеплой", "выкати", "пуш на прод" или просит обновить production.
tools: Bash, Read
model: sonnet
---

# Deploy

## Шаги

1. Проверить, что нет незакоммиченных изменений: `git status`.
2. Запустить тесты: `npm test` или `pytest`.
3. Закоммитить, если есть что коммитить.
4. `git push origin main`.
5. Зайти на сервер по ssh и сделать `git pull` + `docker compose up -d --build`.
6. Прогнать smoke-тесты: `python test/smoke.py`.

## Когда не использовать

- Если ветка не main - не пушить в прод.
- Если smoke падает - откатить через `git revert`.

Поля frontmatter

| Поле | Обязательное | Что делает | | ------------- | ------------ | ----------------------------------------------------------------------- | | name | да | Имя skill. Совпадает с именем директории. | | description | да | По нему Claude решает, подключать ли skill. Самое важное поле. | | tools | нет | Список разрешённых инструментов (Bash, Read, Edit, WebFetch и т.д.). | | model | нет | Принудительная модель: opus / sonnet / haiku. |

Тело файла

Обычный Markdown, который Claude читает как системный промпт при активации skill:

  • Заголовки (##, ###) - визуальные разделители, на семантику не влияют.
  • Шаги, чек-листы, команды - всё через обычные списки и код-блоки.
  • Можно положить рядом дополнительные файлы (templates/, scripts/) и ссылаться на них из тела.

Размер: обычно 30-200 строк. Если перевалили за 300 - вы не skill пишете, а книгу. Разбейте.

Полный пример: skill changelog

---
name: changelog
description: Сгенерировать раздел CHANGELOG.md из git-коммитов с прошлого тега. Использовать перед релизом или когда пользователь просит "обнови changelog", "release notes".
tools: Bash, Read, Edit
---

# Changelog

## Как

1. Найти последний git-тег: `git describe --tags --abbrev=0`.
2. Получить коммиты с этого тега: `git log <tag>..HEAD --oneline`.
3. Сгруппировать по типам: feat, fix, refactor, docs, chore.
4. Добавить новый раздел в начало `CHANGELOG.md` под `## [unreleased]`.
5. Спросить версию у пользователя (semver-bump: major/minor/patch).

## Формат записи

\`\`\`
## [1.2.0] - 2026-05-27

### Added
- ...

### Fixed
- ...
\`\`\`

Антипаттерны

  • Расплывчатый description - Claude не подцепит. Пишите триггеры явно.
  • Skill на 500 строк - разделите на несколько мелких, у каждого свой узкий процесс.
  • Хардкод путей /Users/me/... - используйте относительные или переменные окружения.
  • Skill без tools: для опасных операций - Claude получит все инструменты, включая удаление файлов.

Полезные ссылки