Claude Code: 3 skills, что чинят баги быстрее меня

Знакомо чувство, когда сидишь над кодом, а очередная мелочь ломает весь проект? И ты тратишь часы, выискивая этот баг, вместо того чтобы двигаться вперёд. Я проходил это сотни раз — особенно когда работаешь один и отвечаешь за весь цикл: код, тесты, деплой, поддержка.

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

Как устроены skills: файл, папка, вызов

Скилл — это папка с файлом SKILL.md внутри. В файле две части: YAML-фронтматтер между --- и обычный markdown с инструкциями. Claude подгружает тело скилла только тогда, когда он реально нужен, поэтому длинные чек-листы почти ничего не стоят по контексту, пока лежат без дела.

Где живут скиллы:

~/.claude/skills/<имя>/SKILL.md — личные, доступны во всех твоих проектах.
.claude/skills/<имя>/SKILL.md — проектные, только в этом репозитории (и коммитятся вместе с ним).
<плагин>/skills/<имя>/SKILL.md — из плагина, с неймспейсом плагин:скилл.

Имя папки становится командой. Положил файл в ~/.claude/skills/qa-guard/SKILL.md — вызываешь /qa-guard. Никаких флагов запуска и регистрации: Claude Code следит за папками скиллов и подхватывает изменения прямо в текущей сессии.

Минимальный рабочий SKILL.md выглядит так:

---
description: Что делает скилл и когда его применять. По этому тексту Claude решает, подключать его или нет.
---

Дальше — обычный markdown с инструкциями.

Из полей фронтматтера обязательных нет, но description писать надо: пока скилл не загружен, Claude видит только имя и описание — по ним и принимает решение. Полезные необязательные поля: allowed-tools (какие инструменты разрешены без подтверждения, пока скилл активен), disable-model-invocation: true (запретить автозапуск, оставить только ручной /имя), when_to_use (фразы-триггеры), paths (глобы, при работе с которыми скилл включается).

Вызвать скилл можно двумя способами: написать /имя-скилла руками или просто описать задачу — если она попадает в description, Claude подтянет скилл сам. Подробности — в документации по skills.

Разборы, с которых я в своё время начинал разбираться в теме: Skills для Claude Code: огромный гайд от инженера Anthropic и Claude Code Skills — пишем один .md файл и автоматизируем всё, что раздражает.

Скилл 1: systematic-debugging — не гадаем, а чиним

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

systematic-debugging — готовый скилл из официального плагина superpowers. Его не надо писать самому.

Установка

Внутри сессии claude выполни:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install superpowers@claude-plugins-official
/reload-plugins

После этого скилл доступен как /superpowers:systematic-debugging — или подключается сам, когда ты пишешь про баг, падающий тест или непонятное поведение.

Что он делает

Вместо случайных правок он гонит фиксированный процесс:

Поиск корневой причины. Сначала воспроизвести баг, потом протрассировать его до настоящего источника — а не чинить первый найденный симптом.
Анализ паттерна. Поискать в кодовой базе другие места с той же причиной. Обычно баг не один.
Проверка гипотезы. Сформулировать явную теорию, почему предлагаемый фикс сработает, и проверить её до того, как трогать код.
Реализация. Только теперь пишется исправление.

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

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

Хороший разбор этого и соседних скиллов есть на Хабре: Новые скиллы для Claude Code: systematic-debugging, senior-devops, senior-prompt-engineer. Там же — senior-devops и senior-prompt-engineer, если хочется посмотреть, как устроены большие процессные скиллы.

Скилл 2: qa-guard — защита от регрессий

Исправить баг — полдела. Главное, чтобы он не вернулся и чтобы новое изменение не сломало что-то старое. Для этого я написал себе скилл qa-guard. Это мой личный сторож: он не даёт выкатить в прод изменение, под которое нет теста.

Готового такого скилла в маркетплейсе нет — это мой файл в ~/.claude/skills/qa-guard/SKILL.md. Как я его применяю:

Пишу код или фикс — сам или вместе с Claude Code.
Перед коммитом запускаю /qa-guard. Именно руками: я специально поставил disable-model-invocation: true, чтобы Claude не решал за меня, когда прогонять полный цикл тестов.
Генерация тестов. Claude смотрит на диф и на существующие тесты, дописывает недостающие юнит- и интеграционные, правит устаревшие.
Прогон. Гоняет всё, включая только что сгенерированное.
Отчёт. Если что-то падает — название теста, причина, стектрейс, предложение по фиксу.

Для UI я подключаю Playwright через MCP-сервер: тогда Claude может пройти сценарий в браузере, снять скриншот и проверить DOM — убедиться, что новая кнопка не сломала корзину. Как подключать внешние инструменты, описано в документации по MCP.

SKILL.md для qa-guard

Файл: ~/.claude/skills/qa-guard/SKILL.md

---
description: Проверяет изменения перед коммитом на регрессии — дописывает недостающие тесты, прогоняет весь набор и даёт отчёт. Запускать вручную перед коммитом, PR или деплоем.
disable-model-invocation: true
allowed-tools: Read Grep Glob Bash(git diff *) Bash(git status *)
---

## Анализ изменений

1. Возьми текущий диф рабочей ветки и список затронутых файлов.
2. Для каждого затронутого модуля найди существующие тесты. Отметь модули, у которых тестов нет вообще.

## Генерация и правка тестов

3. На новые функции и изменённое поведение напиши юнит-тесты в том фреймворке,
   который уже используется в проекте. Не тащи новый фреймворк.
4. Если изменения затрагивают UI, обнови или добавь end-to-end сценарий:
   пройти путь пользователя целиком и проверить итоговое состояние страницы,
   а не отдельный DOM-узел.
5. Не переписывай тесты, которые падают по делу. Падающий тест — это находка,
   а не помеха.

## Прогон

6. Запусти весь набор тестов, включая новые.
7. Тяжёлые или долгие проверки выноси в отдельный subagent, чтобы не забивать
   основной контекст выводом.

## Отчёт

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

Похожий подход есть в открытом виде — репозиторий TsakunovR/does-it-work: скилл для Claude Code и Codex, который проверяет, что продукт реально работает, находит баги и строит защиту от регрессий автотестами. Полезно посмотреть, как там сформулированы шаги, даже если писать будешь своё.

Скилл 3: prompt-engineer-assistant — отладка промптов

Баги не заканчиваются на коде. Если продукт работает поверх модели, баг вполне может жить в промпте: пользователю разницы нет, ответ всё равно неправильный. Для этого у меня есть третий свой скилл — prompt-engineer-assistant.

Как он помогает:

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

Скилл незаменим, когда строишь ИИ-системы. Я использую его для своих ассистентов и для клиентских ботов. Например, когда делал бота для заказа цветов, о котором рассказывал в этом кейсе, через него прошёл почти каждый промпт: подобрать тон общения и выбить из ответов канцелярит с первого захода не получается никогда.

SKILL.md для prompt-engineer-assistant

Файл: ~/.claude/skills/prompt-engineer-assistant/SKILL.md

---
description: Отлаживает системные промпты для LLM — находит противоречия и пробелы, предлагает точечные правки. Использовать, когда модель отвечает не в том формате, теряет контекст или игнорирует инструкции.
when_to_use: модель игнорирует инструкции, ответы не в том формате, промпт разросся и перестал работать
---

## Собрать контекст

1. Запроси текущий промпт целиком и два-три примера: желаемый ответ и фактический.
2. Уточни, какая модель используется и какие параметры вызова заданы.

## Разобрать промпт

3. Проверь ясность и однозначность каждой инструкции.
4. Найди противоречия: требование быть кратким рядом с требованием разобрать
   все пункты подробно — классика.
5. Проверь, задан ли формат ответа явно. «Отвечай структурно» — это не формат.
6. Отдельно посмотри, есть ли места, где пользовательский ввод подставляется
   в промпт без ограничений: это вектор для промпт-инъекции.

## Предложить правки

7. Выдай изменения в виде дифа, а не пересказа. Каждая правка — с обоснованием,
   какую именно проблему из пунктов 3-6 она закрывает.
8. Типовые ходы: явный формат ответа, уточнение роли, два-три примера
   в стиле few-shot, разбиение большой задачи на подзадачи.
9. Если проблема в объёме или глубине рассуждения — это настройка вызова,
   а не текста промпта. У актуальных моделей за это отвечают
   `thinking: {type: "adaptive"}` и `output_config: {effort: "low|medium|high|xhigh|max"}`;
   параметры вроде `temperature` у них больше не принимаются.

## Проверить

10. Предложи прогнать новый промпт на тех же входах, что и старый, и сравнить
    ответы построчно.
11. Зафиксируй, что изменилось: стало лучше, стало хуже, не изменилось.

Готового скилла с таким именем в маркетплейсе нет, но идея не моя личная находка: в том же разборе на Хабре есть близкий по смыслу senior-prompt-engineer. Подход к промптам как к коду, который надо отлаживать, а не переписывать наугад, потихоньку становится нормой.

Как это работает вместе: один вечер на проекте

Недавно делал систему скидок для e-commerce. Изменений было много, и я заранее понимал, что где-нибудь да выстрелит.

Код. Claude Code помог написать модули расчёта скидок и стыковку с корзиной.
Баг на локальной машине. При первом запуске — ошибка в консоли: в функцию расчёта прилетал не тот формат данных.
systematic-debugging. Скинул ошибку и логи, вызвал скилл. Он не полез сразу править — сначала воспроизвёл проблему, потом прошёл по гипотезам: валидация входных данных, библиотека дат, недавно добавленный middleware.
Причина. Неявное приведение типов в функции, которая ожидала строку, а получала объект даты. Заодно нашлось ещё одно место с тем же паттерном, куда я бы и не посмотрел, — это и есть шаг «анализ паттерна».
qa-guard. Вместо того чтобы сразу коммитить, запустил его. Он дописал юнит-тесты на расчёт скидок и обновил браузерный сценарий: положить товар в корзину и проверить, что скидка отобразилась.
Прогон. Всё зелёное. Старые функции не пострадали.
Деплой. Только после этого.

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

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

Частые вопросы про Claude Code Skills

Можно ли писать свои скиллы?

Да, и это основной сценарий. Создаёшь папку ~/.claude/skills/имя-скилла/, кладёшь туда SKILL.md с фронтматтером и инструкциями — скилл готов. Никакой сборки и регистрации, Claude Code подхватывает изменения на лету.

Чем скилл отличается от записи в CLAUDE.md?

CLAUDE.md грузится в контекст всегда, скилл — только когда понадобился. Правило вида «в этом проекте пакетный менеджер — pnpm» — это факт, ему место в CLAUDE.md. Многошаговая процедура вроде «как выкатывается релиз» — это скилл. Если раздел в CLAUDE.md превратился в инструкцию из десяти шагов, его пора выносить.

Эти скиллы только для разработчиков?

systematic-debugging и qa-guard — да, они про код. Сам механизм универсален: скилл можно написать под что угодно, где есть повторяющаяся процедура. У меня есть скиллы под разбор клиентских созвонов и под подготовку контента, кода там нет ни строчки.

Надо ли платить за каждый скилл отдельно?

Нет. Скилл — это просто markdown-файл в твоей папке, никакой отдельной оплаты за него не существует. Платишь ты за доступ к Claude Code, а сколько у тебя скиллов — один или сто — на цену не влияет.

Как Claude решает, какой скилл применить?

По полю description (и when_to_use, если оно есть). Пока скилл не загружен, Claude видит только имя и это описание — тело файла в контекст не попадает. Отсюда практическое правило: описание пишется не «что это за скилл», а «когда его брать», с формулировками, похожими на реальные запросы. Расплывчатое описание — главная причина, почему скилл лежит и не срабатывает.

Где брать готовые скиллы?

Официальный маркетплейс плагинов: /plugin marketplace add anthropics/claude-plugins-official, дальше /plugin покажет список. Плюс открытый стандарт Agent Skills и репозитории на GitHub — скиллы совместимы между инструментами. Свои наработки я выкладываю здесь, в блоге.

Если хочешь системно разобраться в работе с Claude — не использовать его как чат, а встроить в рабочие процессы, — у меня есть гайд «Claude как рабочий инструмент». Там собраны готовые системы и команды, которые настраиваются за вечер.