Есть характерный момент в работе с Claude Code, когда вы ловите себя на копировании. Третий раз за неделю вы вставляете в чат один и тот же чек-лист перед релизом. Или надиктовываете одну процедуру: посмотри диф, собери описание изменений, оформи pull request. Инструкция уже отточена — но живёт она в буфере обмена, а не в проекте.

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

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

В главе 5 вы научились описывать проект в CLAUDE.md и раскладывать правила по .claude/rules/. Это память проекта: она в контексте всегда. Именно поэтому в CLAUDE.md хорошо ложатся факты — стек, соглашения об именовании, команда запуска тестов.

Проблема начинается, когда факт разрастается в процедуру. Раздел «Как мы деплоим» из трёх строк превращается в двадцать шагов с проверками, и эти двадцать шагов оплачиваются токенами в каждом ходе — включая те, где вы просто просите переименовать переменную. Скилл устроен иначе: в контексте постоянно находится только его описание, а тело загружается лишь в момент вызова. Это главное отличие от CLAUDE.md и главная причина хранить длинный справочный материал в скилле.

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

• Чем скилл отличается от CLAUDE.md и когда выбирать что
• Из каких частей состоит скилл и почему файл называется строго SKILL.md
• Как вызвать скилл вручную и как Claude вызывает его сам
• На каких уровнях живут скиллы и кто кого перекрывает
• Откуда берётся имя команды и почему поле name его не меняет

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

• Скилл — директория с файлом SKILL.md внутри, содержащим YAML-frontmatter и markdown-инструкции. Claude Code добавляет скилл в свой набор инструментов.
• Frontmatter — блок метаданных между строками ---. Читается, только если открывающий --- — первая строка файла.
• description — поле frontmatter: что делает скилл и когда его применять. По этому тексту Claude решает, вызывать ли скилл сам.
• Personal-скилл — скилл в ~/.claude/skills/, доступный во всех ваших проектах.
• Project-скилл — скилл в .claude/skills/ репозитория, доступный всем участникам проекта.
• Bundled-скилл — встроенный скилл Claude Code: /doctor, /code-review, /debug, /loop и другие.

Анатомия скилла

Скилл — это не одиночный файл, а директория. Внутри неё обязателен файл с именем строго SKILL.md: ни skill.md, ни deploy.md не подойдут.

.claude/
└── skills/
    └── release-checklist/
        └── SKILL.md

Сам файл состоит из двух частей — frontmatter и тела:

---
name: Чек-лист релиза
description: Проверяет готовность ветки к релизу. Использовать, когда просят подготовить релиз или выкатить версию.
---

Перед релизом всегда проверяй по порядку:

1. Все тесты в `npm test` проходят.
2. В `CHANGELOG.md` есть запись для новой версии.
3. Версия в `package.json` увеличена по semver.

Если пункт не выполнен, останови проверку и сообщи, какой именно.

Выше нижнего --- — метаданные, ниже — инструкции, которые получит Claude. Здесь прячется ловушка: frontmatter распознаётся, только если открывающий --- стоит первой строкой файла. Поставьте перед ним заголовок или комментарий — и Claude Code сочтёт содержимым скилла весь файл целиком, вместе с этими ---. Скилл не сломается, но останется без description, а значит, сам Claude вызвать его не сможет.

Обязательных полей во frontmatter нет ни одного, но description рекомендуется всегда:

---
description: Собирает описание pull request по дифу ветки. Использовать, когда просят оформить PR.
---

Два способа вызова

Скилл можно запустить вручную — командой /release-checklist. А можно не запускать: Claude читает description всех доступных скиллов и сам решает, подходит ли какой-то из них под вашу задачу.

Отсюда следствие. Описание вида «Скилл для релизов» валидно, но бесполезно: в нём нет слов, которые вы реально произносите. Хорошее description отвечает на два вопроса — что скилл делает и когда его применять — и содержит формулировки из вашей обычной речи: «выкатить версию», «проверить перед деплоем».

Где живут скиллы и кто кого перекрывает

Уровней четыре:

При совпадении имён порядок такой: enterprise перекрывает personal, а personal перекрывает project. Разберём пример из документации, потому что он контринтуитивен. Скилл deploy есть и в ~/.claude/skills/deploy/, и в .claude/skills/deploy/ вашего репозитория. Вы работаете внутри репозитория и вызываете /deploy. Запустится персональный скилл, а не проектный.

Привычная логика «локальное важнее общего» здесь не работает: приоритет отдан вам как пользователю, а не проекту. Если команда договорилась о проектном deploy, а у вас лежит одноимённый личный, вы будете единственным, у кого команда делает не то, что у всех. Переименуйте личный — конфликт исчезнет.

Откуда берётся имя команды

Это вторая крупная ловушка новичка. Имя команды у personal- и project-скилла берётся из имени директории, а не из поля name.

~/.claude/skills/deploy-staging/SKILL.md   # вызывается как /deploy-staging

Даже если внутри написано name: Выкатка на стейджинг, команда останется /deploy-staging. Поле name задаёт только подпись в списках скиллов. Хотите другую команду — переименуйте директорию.

Заодно отметим: скиллы слиты с кастомными командами. Файл .claude/commands/deploy.md и директория .claude/skills/deploy/ оба дают /deploy; старые файлы в commands/ продолжают работать. Если существует и то и другое — побеждает скилл. Скилл даёт больше: директорию под вспомогательные файлы, frontmatter для контроля вызова и автозагрузку моделью.

Готовые примеры у вас уже есть — встроенные /doctor, /code-review, /debug, /loop. Весь список доступного в сессии открывает /skills.

Что происходит при вызове

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

Отсюда два вывода. Первый: пишите инструкции как постоянно действующие правила («всегда проверяй X»), а не как одноразовый список шагов, — они будут влиять на разговор и дальше. Второй: каждая строка тела — повторяющаяся стоимость в токенах, поэтому держите тело кратким, а справочный материал выносите в отдельные файлы рядом с SKILL.md.

Приятная мелочь: Claude Code следит за директориями скиллов, и правки подхватываются прямо в текущей сессии. Перезапуск нужен, только если вы создали каталог скиллов верхнего уровня, которого не было на старте сессии.

У frontmatter есть и другие поля — аргументы, запуск в изолированном контексте через context: fork, установка готовых скиллов со стороны. Это разберём в следующих уроках главы.

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

• Файл назван не SKILL.md. Имя строгое, регистр важен: skill.md или deploy.md внутри директории скилла не будут найдены. Директорию называйте как хотите, файл внутри — всегда SKILL.md.
• Frontmatter не с первой строки. Заголовок или комментарий перед открывающим -- — и метаданные не читаются. Файл превращается в скилл без description, вызывать который умеете только вы.
• Ожидание, что name меняет команду. Поле name — подпись в списке, не более. Команда берётся из имени директории, и сменить её можно только переименованием директории.
• Длинная процедура оставлена в CLAUDE.md. Она работает, но оплачивается токенами в каждом ходе, включая те, где не нужна. Процедурам место в скилле, фактам о проекте — в CLAUDE.md.

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

• Скилл заменяет CLAUDE.md? — Нет, они дополняют друг друга. CLAUDE.md — факты, нужные всегда; скилл — процедура, нужная изредка, но целиком.
• Что будет, если description не указать? — Описание возьмётся из первого абзаца содержимого. Вручную скилл вызывать можно, но автоматический вызов станет непредсказуемым.
• Скилл deploy есть и у меня, и в проекте. Какой запустится? — Персональный: personal перекрывает project. Одноимённые скиллы лучше не заводить.
• Нужно ли перезапускать Claude Code после правки скилла? — Нет, правки подхватываются в текущей сессии. Перезапуск нужен только при создании нового каталога скиллов верхнего уровня.
• Как посмотреть доступные скиллы? — Командой /skills: она открывает меню со всеми скиллами текущей сессии.

Итоги

Вы разобрали устройство скилла целиком: директория плюс SKILL.md, frontmatter с первой строки, description как точка входа для автоматического вызова и имя директории как источник имени команды. Вы знаете четыре уровня хранения и помните правило приоритета, из-за которого личный deploy тихо перебивает проектный. И, что важнее всего, вы понимаете экономику: тело скилла ничего не стоит, пока не вызвано, — поэтому процедуры переезжают из CLAUDE.md в скиллы, а не наоборот.

Картина мира собрана, дальше практика. В следующих уроках вы напишете свои скиллы, научитесь передавать в них аргументы и подключать готовые решения со стороны. Ничего сложнее прочитанного там не будет — только больше рычагов управления.