Как написать навык агента (SKILL.md) — за один вечер и без кода

Самая обидная ошибка с навыками выглядит так: ты написал отличную инструкцию, положил в проект — и агент её ни разу не применил. Молча. Будто файла нет.

Почти всегда виновато не тело навыка, а одна строчка description. Разберём весь путь по шагам — и на шаге 6 починим именно её.

Кода писать не придётся: навык агента — это папка с текстовым файлом.

1. Выбери задачу, которую объяснял дважды

Хороший кандидат — то, что ты уже повторял агенту в разных сессиях. Не «сделай мне хорошо», а конкретная процедура:

• как у вас оформляется новый компонент (папка, файлы, экспорт);
• как подготовить релиз перед выкаткой;
• как пишется сообщение коммита;
• как выложить отчёт в нужном формате.

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

2. Создай папку

Навыки проекта лежат в .claude/skills/, личные — в ~/.claude/skills/. Возьмём проектный: он поедет в репозиторий и будет работать у всей команды.

mkdir -p .claude/skills/new-component
touch .claude/skills/new-component/SKILL.md

Имя папки — строчными буквами через дефис. Оно же дальше пойдёт в поле name.

3. Напиши шапку

Открой SKILL.md и первым делом поставь frontmatter — YAML между двумя тройными дефисами:

---
name: new-component
description: Создать новый UI-компонент по правилам проекта. Использовать,
  когда просят добавить компонент, кнопку, карточку или новый экран.
---

Обязательных полей два. name — до 64 символов, строчные буквы, цифры и дефисы. description — до 1024 символов, и именно в нём вся магия (шаг 6).

4. Напиши тело — шагами, а не пожеланиями

Дальше идёт обычный Markdown. Пиши так, будто объясняешь стажёру, который умеет программировать, но не знает ваших договорённостей.

Создавая компонент:

1. Папка `src/components/ProductCard/` — имя в PascalCase.
2. Внутри `index.tsx` с именованным экспортом. Дефолтных экспортов у нас нет.
3. Стили — токенами из `tokens.css`, без хардкода цветов.
4. Рядом положи `ProductCard.test.tsx` с одним smoke-тестом.

Не трогай `src/legacy/` — там старая система.

Три правила, которые отличают рабочий навык от бесполезного:

• Конкретные пути и имена. «В нужной папке» — мусор, src/components/ — инструкция.
• Запреты не менее важны разрешений. Строка «не трогай legacy» экономит часы.
• Коротко. Навык читается целиком, когда сработал. Раздутое полотно на 400 строк размывает главное — ровно как в хорошем промпте.

Если материала много — вынеси подробности в отдельный файл:

new-component/
├── SKILL.md
└── references/
    └── naming.md

В SKILL.md оставь ссылку на него. Агент откроет references/naming.md, только если дойдёт до именования. Это и есть прогрессивное раскрытие: платишь за то, что реально прочитано.

5. Убедись, что агент вообще видит навык

Перезапусти сессию: навыки подхватываются при старте. Дальше спроси прямо — «какие навыки тебе доступны». В списке должна появиться твоя строка.

Не появилась — проверь три вещи: папка ровно .claude/skills/, файл называется SKILL.md заглавными, и frontmatter открыт-закрыт тремя дефисами. Опечатка в YAML — самая частая причина.

6. Проверь срабатывание — и почини описание

Теперь главный тест. Начни новую сессию и сформулируй задачу так, как сформулировал бы обычно:

добавь карточку товара

Агент должен сам вспомнить про навык. Не вспомнил — дело в description. Он видит заранее только его: это не заголовок для людей, а условие срабатывания.

Разница в том, что во втором варианте есть слова, которыми ты реально просишь: «кнопку», «карточку», «экран». Формула простая: что делает + когда применять + слова пользователя.

Хочешь наоборот — чтобы навык не запускался сам, а только по твоей команде? Добавь в шапку disable-model-invocation: true, и он останется ручным: вызывается как /new-component.

Что получится

Файл на 20–30 строк, который живёт в репозитории. Новая сессия, новый человек в команде, другая машина — агент всё равно сделает компонент по вашим правилам, без напоминаний.

И приятный бонус: формат SKILL.md — открытый стандарт, его поддерживает не только Claude Code. Навык переносится в другой совместимый инструмент как обычный файл.

Чем навык лучше файла с правилами проекта?

Файл правил грузится всегда и целиком — он про общие договорённости. Навык подтягивается под конкретную задачу, поэтому в нём можно позволить себе детали, за которые в общем файле пришлось бы платить контекстом каждый запрос. Как давать агенту общий контекст — разбираем здесь.

Навык не сработал, хотя описание точное. Что ещё?

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

А если навыку нужен доступ к внешней системе?

Навык — это инструкция, он сам никуда не ходит. Если нужны живые данные из базы или трекера, это задача для MCP-сервера: сравнение двух подходов — в статье навыки или MCP.