Откройте свою историю промптов за последнюю неделю. Сколько раз вы писали агенту примерно одно и то же? «Сделай code review. Проверь типизацию, никаких any. camelCase для функций, тесты для публичного API.» Три раза? Десять? Каждый такой повтор это потерянные минуты и риск, что в очередной раз вы забудете половину своих же требований.

У проблемы есть второй симптом. Ваш CLAUDE.md распух до трёхсот строк, потому что в него дописали все процедуры подряд: как оформлять коммиты, как катить миграции, как проводить ревью. Файл читается на каждый запрос и постепенно превратился в свалку.

И там, и там ответ один: skill. Skill это SOP для агента, стандартная операционная процедура. Записали правило один раз, и агент следует ему всегда, без напоминаний и без копипасты промпта из заметок.

Skill это один markdown-файл

Никакой магии внутри нет. Skill живёт по пути .claude/skills/<имя>/SKILL.md и представляет собой обычный markdown с YAML-шапкой. Хорошая структура умещается в пять блоков:

  • frontmatter с полями name и description. Именно description агент читает при сканировании проекта.
  • Instructions, пронумерованные шаги: что конкретно делать, когда skill сработал.
  • Examples, один-два примера входа и выхода. Не десять, десять одинаковых только раздувают файл.
  • Constraints, границы: чего skill не делает. Агенты любят расползаться на соседние задачи, и рамки их держат.
  • Output Format, в каком виде выдавать результат, если skill что-то генерирует.

Progressive disclosure: почему это дёшево

Возникает резонный вопрос: если у меня десять skill’ов, они же забьют весь контекст. Нет, и вот почему. При старте Claude Code сканирует все skill’ы, но не грузит их тела. Он читает только description каждого, одну-две строки. Для нового запроса агент прикидывает по этим описаниям, какой skill уместен, и подтягивает целиком лишь его. Остальные в контекст не попадают вообще.

Этот приём называют progressive disclosure, постепенное раскрытие. Тот же принцип работает во всей контекстной инженерии: агент читает ровно столько, сколько нужно для текущего шага, и ни строкой больше. Благодаря ему можно держать хоть двадцать skill’ов в проекте и не платить за них контекстом, пока они молчат.

Бюджет токенов: 2000 на skill

Про эту деталь часто забывают, а зря. Когда skill активировался, он грузится в контекст целиком, и каждый его токен это минус один токен для вашей реальной задачи.

Посчитаем. Пять активных skill’ов по две тысячи токенов дают десять тысяч, а это уже пять процентов окна двухсоттысячной модели, и всё только на инструкции. Сверх них ещё пойдёт CLAUDE.md, история диалога и сам ваш вопрос.

Из правила есть красивое исключение. Очень большие skill’ы, вроде методологического FPF на десятки тысяч строк, собирают не монолитом. Сам SKILL.md остаётся компактным, а внутри лежит индекс из сотен файлов. Агент читает индекс, находит нужный раздел и подгружает только его. По сути это RAG внутри skill’а.

Description решает всё

Из всех частей skill’а важнее всего description, потому что он работает как поисковый запрос наоборот. Сравните два варианта.

Плохой: «Skill для работы с кодом». Слишком общо. Агент либо цепляет его на каждый чих про код, либо не понимает, когда он вообще уместен, и не включает никогда.

Хороший: «Code review для TypeScript: проверка типизации и отсутствия any, naming conventions, покрытие тестами, упрощение вложенных цепочек. Активируется при review, ревью, проверке кода». Тут есть конкретика, перечень того, что skill проверяет, и явные триггер-глаголы в конце. Русские и английские сразу, потому что промпты вы пишете на обоих языках.

Из этого следует диагностическое правило. Написали «сделай review», а skill не подхватился? Виноват description, а не skill. Перепишите описание, добавьте слова, которыми вы реально пользуетесь, и проверьте снова.

Соберём skill за пять минут

Хватит теории, сделаем рабочий skill для code review. Создаём папку:

mkdir -p .claude/skills/code-review

Кладём в неё файл SKILL.md:

---
name: code-review
description: >
  Code review для TypeScript: типизация и отсутствие any,
  naming conventions, покрытие тестами, упрощение.
  Активируется при review, ревью, проверке кода.
---

## Instructions
1. Упрощение: лишние абстракции, цепочки вызовов длиннее двух уровней.
2. Типизация: нет any и unknown, все параметры типизированы.
3. Тесты: у каждой публичной функции есть happy path и error path.
4. Стандарты: имена, форматирование, структура файлов.

## Output Format
Для каждой находки: файл и строка, проблема одним предложением,
исправление с кодом, severity CRITICAL / WARNING / INFO.

Готово. Теперь в новой сессии напишите обычным языком: «сделай review файла src/auth/service.ts». Если description составлен верно, агент сам подхватит skill, пройдётся по четырём приоритетам и выдаст находки в заданном формате. Слово «skill» в запросе даже не понадобится, в этом и смысл.

Skill дополняет CLAUDE.md, а не заменяет

Последнее, что стоит держать в голове. Иногда skill и CLAUDE.md противоречат друг другу: один говорит одно, второй другое. В такой ситуации побеждает CLAUDE.md, он выше в иерархии. Поэтому делите зоны заранее: правила проекта, стек и запреты живут в CLAUDE.md, а повторяющиеся процедуры переезжают в skill’ы.

Начать проще, чем кажется. Загляните в историю промптов, найдите два текста, которые повторяются трижды и чаще, и превратите их в два skill’а по этому шаблону. Через неделю такой привычки вы поймёте, что перестали объяснять агенту одно и то же по кругу.

Тема: Claude Code