Как написать skill для Claude Code под задачи QA: структура, описание, проверки и тест самого skill

Коротко

Skill — это папка с файлом SKILL.md: коротким описанием, когда его применять, и инструкцией, как работать. Claude Code подгружает его по необходимости, а не держит в контексте всегда.
Всё решает поле description: по нему агент понимает, что skill относится к текущей задаче. Расплывчатое описание — skill никогда не сработает.
Хороший skill похож на чек-лист для коллеги: входные данные, шаги, критерий готовности, чего делать нельзя.
То, что должно выполняться всегда и без исключений, не skill, а hook или проверка в CI. Skill — знания и порядок работы под конкретный тип задач.
Skill нужно тестировать: срабатывает ли он на нужные запросы, не срабатывает ли на лишние и даёт ли результат, который вы можете проверить.

Где место skill среди остального харнеса

В разборе харнеса для AI-агентов я описывал слои: CLAUDE.md, skills, hooks и права, агенты-ревьюеры, CI. Коротко о разнице:

Слой	Когда срабатывает	Для чего
CLAUDE.md	всегда загружен	короткие универсальные правила проекта
Skill	когда задача подходит под описание	порядок работы и знания под тип задачи
Hook	на событие, гарантированно	обязательные проверки и запреты
Агент-ревьюер	по запросу	независимый взгляд на результат

Для QA типичные кандидаты в skills: ревью набора тестов или датасета, оформление баг-репорта для LLM по шаблону, подготовка тест-плана, разбор отчёта о провалах evals. Если правило нужно соблюдать всегда (не читать .env, не коммитить без команды), оно живёт в правах и hooks: инструкцию skill агент может пропустить.

Структура

Skill лежит в каталоге проекта .claude/skills/<имя>/SKILL.md (или в пользовательском каталоге для всех проектов). Файл начинается с блока метаданных, затем идёт текст инструкции. Минимально нужны name и description:

---
name: bug-report-llm
description: Оформляет баг-репорт по дефекту LLM-ассистента по шаблону. Используй, когда нужно описать галлюцинацию, неверный ответ, нарушение формата, утечку или провал метрики и приложить воспроизведение.
---

# Баг-репорт по дефекту LLM

...инструкция...

Рядом с SKILL.md можно положить вспомогательные файлы: шаблоны, скрипты, примеры. На них ссылаются из инструкции, и агент читает их по мере необходимости. Это экономит контекст: основной файл остаётся коротким. Точный набор дополнительных полей метаданных и поведение подгрузки зависят от версии Claude Code, поэтому сверяйтесь с актуальной документацией.

Описание: поле, которое всё решает

Агент видит список skills с их описаниями и решает, какой из них применить. Тело загружается только после этого решения. Поэтому описание должно отвечать на два вопроса: что делает skill и когда его использовать. Сравните:

Плохо: «Помощник по тестированию».
Хорошо: «Ревьюит golden-датасет для RAG: покрытие по типам вопросов, дубли, пустые эталоны. Используй, когда просят проверить, дополнить или оценить качество датасета evals».

Включайте в описание слова, которыми пользователь действительно называет задачу: «датасет», «evals», «баг-репорт», «тест-план». Не делайте описание длинным романом, 1–3 предложения хватает.

Тело: как писать инструкцию

Принципы, которые я использую:

Входные данные. Что агент должен прочитать первым (путь к файлу, формат), и что делать, если данных нет: спросить, а не угадывать.
Шаги в порядке выполнения. Нумерованный список, каждый шаг — действие, которое можно проверить.
Критерии готовности. По чему понять, что работа закончена: «в отчёте есть таблица покрытия», «каждая проблема имеет id записи».
Ограничения. Чего не делать: не менять данные без команды, не придумывать эталоны, не запускать платные прогоны без подтверждения.
Формат результата. Какой файл создать и какие разделы в нём.
Честность. Что агент должен сообщать явно: что не удалось проверить, какие допущения сделал.

Не вставляйте в skill то, что агент и так знает (как работает pytest). Вставляйте то, что специфично для вашего проекта: структуру датасета, договорённости об именах, пороги, шаблоны.

Пример: skill для ревью набора evals

---
name: evals-dataset-review
description: Проверяет golden-датасет для RAG или чат-бота (CSV): покрытие по типам вопросов, дубли, пустые эталоны, отсутствие вопросов без ответа. Используй, когда просят проверить, оценить или улучшить датасет для evals.
---

# Ревью golden-датасета

## Вход
Путь к CSV. Ожидаемые колонки: id, question, expected_answer, expected_sources, type, difficulty.
Если колонок не хватает, назови отсутствующие и остановись, ничего не придумывай.

## Шаги
1. Запусти `python scripts/check_dataset.py <путь>` и приведи вывод.
2. Посчитай распределение по `type` и `difficulty`. Отметь типы, где меньше 5 записей.
3. Найди дубликаты и почти дубликаты вопросов (совпадение после нормализации регистра и пробелов).
4. Проверь, что есть вопросы типов no_answer и adversarial.
5. Выбери 5 случайных записей и проверь по исходным документам, что эталон верен.
6. Сформулируй список проблем по убыванию критичности, у каждой укажи id записей.

## Критерий готовности
Файл `reports/dataset-review.md` содержит: таблицу покрытия, список проблем с id,
перечень того, что не удалось проверить.

## Нельзя
- Менять исходный CSV. Предлагай правки списком, вносить их буду я.
- Придумывать эталонные ответы. Если эталона нет, помечай запись как требующую разметки.
- Утверждать, что датасет «достаточен», без цифр покрытия.

Скрипт scripts/check_dataset.py в примере — тот самый проверочный код покрытия из разбора про golden-датасет. Вынесение механической части в скрипт — хороший приём: агент не тратит токены на подсчёт, а результат воспроизводим.

Как проверить, что skill работает

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

Срабатывание. Составьте 10 реплик, на которых skill должен включиться, в том числе в разных формулировках («проверь датасет», «оцени вопросы для evals», «что не так с golden.csv»). Убедитесь, что агент использует именно его.
Ложные срабатывания. Ещё 10 реплик, близких по теме, но не про датасет («напиши тест на pytest»). Skill включаться не должен. Если включается, сузьте описание.
Результат. Дайте skill заведомо плохой датасет с известными дефектами (дубли, пустой эталон, нет no_answer) и посмотрите, найдёт ли он их все. Это обычный тест с известными ошибками, как для статического анализатора.
Стабильность. Повторите прогон несколько раз. Если находки каждый раз разные, инструкция слишком расплывчата, добавьте конкретики и шагов.
Границы. Проверьте запреты: попросите «исправь эталоны сам» и посмотрите, откажется ли агент менять файл.

Результат этих проверок удобно записать как небольшую таблицу «реплика, ожидание, факт». Так ревью skill становится повторяемым, и после правок описания вы быстро увидите регрессию.

Типичные ошибки

Слишком широкий skill. «Всё про тестирование» не срабатывает и не помогает. Один skill — одна задача.
Дублирование CLAUDE.md. Одни и те же правила в двух местах расходятся.
Обещание гарантий. Не пишите «всегда делай X» там, где нужна гарантия: для этого есть hooks и CI.
Секреты и данные в skill. Файлы skills попадают в репозиторий, поэтому ключей, паролей и клиентских данных там быть не должно.
Чужие skills без чтения. Skill — это инструкции для агента с доступом к вашим файлам. Прежде чем подключать чужой, прочитайте его целиком, включая скрипты.

Что дальше

Выберите одну повторяющуюся QA-задачу и опишите её шагами. Если шагов больше пяти, это хороший кандидат для skill.
Напишите описание из двух предложений и проверьте его на 10 репликах.
Подробнее о том, как skill встраивается в остальные слои, читайте в разборе харнеса, а о проверке агентов, которые пользуются инструментами, — в статье про тестирование агентов и MCP.