У каждого разработчика есть набор повторяющихся просьб к агенту: «посмотри, что я наменял, и напиши сообщение коммита», «проверь компонент по нашему чек-листу». Каждый раз вы формулируете это заново — и каждый раз чуть иначе, поэтому и результат чуть иной.

Скилл превращает такую просьбу в постоянную единицу: вы описываете процедуру один раз, а дальше либо вызываете её командой, либо Claude подхватывает её сам по описанию. После этого урока вы сможете пройти путь от пустой директории до работающего /skill-name.

Что уже умеем / что добавим

Вы уже знаете, что скилл — это файл SKILL.md с YAML-frontmatter, что его тело попадает в контекст только при вызове, и чем он отличается от CLAUDE.md, который в контексте всегда. Теперь сделаем скилл руками: создадим директорию, напишем описание, проверим вызов и разберём поля, управляющие запуском.

Что вы узнаете в рамках статьи

• Как создать скилл тремя командами и проверить, что он работает
• Как написать description, по которому Claude действительно вызовет скилл
• Чем персональный скилл отличается от проектного и что где уместно
• Как запретить Claude вызывать скилл самому и как предодобрить инструменты
• Как разнести материал по вспомогательным файлам и что делать, если скилл молчит

Ключевые термины

• SKILL.md — единственный обязательный файл скилла. Имя строго заглавными, иначе скилл не найдётся.
• Frontmatter — YAML-блок между строками --- в самом начале файла. Задаёт метаданные скилла.
• description — текст «что делает + когда применять». По нему Claude решает, подходит ли скилл к запросу.
• when_to_use — дополнительное поле для триггерных фраз и примеров запросов; добавляется к описанию.
• allowed-tools — инструменты, доступные Claude без запроса разрешения в течение хода, вызвавшего скилл.
• Live change detection — отслеживание директорий скиллов: правки SKILL.md подхватываются в текущей сессии.

Три шага до работающего скилла

Скилл создаётся тремя действиями: директория, файл, проверка.

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

Имя команды берётся из имени директории, а не из поля name: директория summarize-changes даёт команду /summarize-changes.

Вот полный скилл из документации, который резюмирует незакоммиченные изменения:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Обратите внимание на строку !git diff HEAD``. Это динамический контекст: команда выполняется до того, как содержимое скилла уйдёт модели, и её вывод подставляется на место плейсхолдера. Claude получает готовый diff, а не инструкцию его получить. Здесь достаточно знать, что так можно; подробно разберём в уроке 6.4.

Проверка: наберите /summarize-changes. Если директории скиллов верхнего уровня не было на старте сессии, перезапустите Claude Code — дальнейшие правки SKILL.md подхватятся уже без перезапуска.

Description: по нему Claude принимает решение

Тело скилла Claude не видит, пока скилл не вызван. Всё, чем он располагает при выборе, — это description. Отсюда три правила.

Начинайте с ключевого сценария, а не с общих слов. Включайте те слова, которые пользователь реально произносит: «diff», «commit message», «что изменилось». И пишите по формуле «что делает + когда применять» — вторая половина важнее первой. Сравните:

description: Помощник по git

description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
when_to_use: "что я наменял, напиши коммит, посмотри мой diff"

Первое описание не сработает никогда: под «помощника по git» подходит любой запрос и одновременно ни один. Второе перечисляет конкретные поводы. Поле when_to_use добавляется к описанию и удобно для триггерных фраз. Учитывайте ограничение: совокупный текст description и when_to_use обрезается на 1536 символах.

Персональный или проектный

Персональный скилл лежит в ~/.claude/skills/<name>/SKILL.md и доступен во всех ваших проектах. Проектный — в .claude/skills/<name>/SKILL.md и виден только в этом репозитории.

Разделяйте по природе знания. Личные привычки — формат заметок, любимый стиль резюме диффа — персональные: команде они не нужны. Соглашения команды — правила именования веток, чек-лист ревью — проектные, и их коммитят в git вместе с кодом. Тогда новый участник получает их вместе с git clone, а изменения проходят через обычный pull request.

Кто может вызвать скилл и какими инструментами

По умолчанию скилл вызывается двумя способами: вы командой и Claude сам. Два поля меняют это поведение:

disable-model-invocation: true ставят на действия с побочными эффектами — коммит, деплой, отправка сообщений: такое запускает человек. Приятный бонус: описание убирается из контекста и перестаёт занимать место в листинге.

user-invocable: false — обратный случай: скилл нужен как фоновое знание для Claude, но осмысленной командой не является, поэтому его прячут из меню /.

Поле allowed-tools предодобряет инструменты: перечисленное Claude использует без запроса разрешения в течение хода, вызвавшего скилл. С вашим следующим сообщением грант снимается.

---
description: Creates a git commit with a conventional commit message
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Stage the relevant files and create a commit following the Conventional Commits format.

Здесь важно не ошибиться: allowed-tools не ограничивает набор инструментов. Остальное по-прежнему доступно Claude по обычным правилам разрешений. Для ограничения есть обратное поле disallowed-tools — оно убирает инструменты из пула, пока скилл активен.

Вспомогательные файлы и диагностика

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

api-client/
├── SKILL.md
├── reference.md
├── examples.md
└── scripts/
    └── check.sh

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

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Скрипты запускайте через ${CLAUDE_SKILL_DIR} — эта переменная разворачивается в директорию SKILL.md, и путь резолвится одинаково независимо от рабочей директории.

Если скилл не срабатывает сам, порядок такой. Проверьте description на слова, которые вы реально произносите. Спросите «What skills are available?» — если скилла нет в ответе, дело не в формулировке. И вызовите напрямую: /skill-name работает даже при пустых метаданных.

Именно так выглядит битый YAML: Claude Code загружает тело с пустыми метаданными, поэтому команда работает, но сопоставлять по описанию нечего и автовызова нет. Ошибку парсинга видно с флагом --debug, а найти все такие файлы разом помогает claude plugin validate ~/.claude/skills.

Частые ошибки

• Файл назван skill.md или deploy.md. Имя строго SKILL.md, заглавными. Иначе директория есть, а скилла нет.
• Открывающий -- не на первой строке. Frontmatter читается, только если -- — самая первая строка. Пустая строка выше — и весь файл, включая --, считается содержимым.
• Расчёт на name как на имя команды. У персональных и проектных скиллов команду задаёт имя директории; name меняет подпись в списках.
• Ожидание, что allowed-tools ограничит Claude. Это предодобрение, а не рамка. Ограничивает disallowed-tools.

Наиболее частые вопросы

• Нужно ли перезапускать Claude Code после правки скилла? — Нет, правки SKILL.md подхватываются в текущей сессии. Перезапуск нужен, только если вы создали директорию скиллов верхнего уровня, которой не было на старте.
• Обязательно ли поле description? — Формально все поля необязательны, но без описания Claude не вызовет скилл сам. Если поля нет, берётся первый абзац содержимого.
• Скилл срабатывает слишком часто, что делать? — Сделать description конкретнее или поставить disable-model-invocation: true, оставив вызов за собой.
• Сохранится ли предодобрение инструментов на следующий ход? — Нет, грант allowed-tools снимается с вашим следующим сообщением.
• Можно ли передавать скиллу аргументы? — Можно, это тема следующего урока.

Итоги

Вы прошли полный путь: создали директорию, написали SKILL.md, проверили вызов и разобрались, какие поля управляют поведением. Главное — про description: тело скилла Claude увидит только после вызова, а решение о вызове принимает целиком по описанию. Хорошее описание — половина работающего скилла. Второе по важности: disable-model-invocation оставляет опасные действия за человеком, а allowed-tools лишь убирает лишние вопросы на один ход.

Дальше скиллы станут гибче. В следующем уроке мы научим их принимать аргументы, чтобы одна процедура работала с разными входными данными, а позже разберём динамический контекст и запуск в изолированном контексте через context: fork. Пока же соберите один-два скилла под свои настоящие повторяющиеся задачи.