Скиллы Claude Code: рутина в скилл, ошибка агента в правило

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

Пришлось разбираться, как скиллы выглядят у людей, которые с ними правда работают, и что Anthropic поменял в своих рекомендациях под модели 5.5. Вы разрежете свою рутину на скиллы, соберёте первый через /skill-creator и заведёте цикл, в котором каждая ошибка агента становится правилом внутри скилла.

Почему рутину лучше держать в скиллах Claude Code, а не в CLAUDE.md

Первое, что приходит в голову, – дописать все свои порядки в CLAUDE.md. Но этот файл попадает в каждую сессию целиком. Знания, которые нужны раз в неделю, занимают контекст каждый день.

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

Отсюда принцип, на котором держится весь конвейер. Объясняете агенту что-то второй раз – это кандидат в скилл. Агент ошибся – ошибка становится правилом внутри того скилла, где она случилась.

Момент для этого удобный. В октябре 2026 года, вместе с выходом моделей Claude 5.5, Anthropic обновил официальный гайд по скиллам. После обновления часть привычных приёмов пора пересмотреть, и новые правила пригодятся уже при сборке первого скилла.

Как нарезать работу и собрать первый скилл для Claude через /skill-creator

Хороший пример нарезки – конвейер одного QA-инженера. За пару месяцев у него сложилось 10 скиллов, и вместе они покрывают его работу от начала до конца: критерии приёмки, деплой, разбор логов, баг-репорты, итоговый отчёт о тестировании. Каждый скилл, по сути, отвечает за один этап, который раньше приходилось заново описывать агенту.

Кстати, писать скилл с нуля вручную не обязательно. У Anthropic есть официальный плагин skill-creator. В Claude Code его сначала ставят командой /plugin install skill-creator@claude-plugins-official, а потом вызывают через /skill-creator. Он расспрашивает, что скилл должен делать, набрасывает черновик, прогоняет на нём тестовые запросы и дорабатывает результат по итогам прогона.

Готовый скилл устроен примерно так. Это скилл баг-репорта из того же конвейера.

skills/bug-report/
├── SKILL.md ← когда применять, порядок, правила, пример
├── references/
│ ├── developer-formats.md ← развёрнутые форматы для разработчика
│ ├── neuro-critic.md ← проверка текста перед отправкой
│ └── project-config.md ← что настроить под свой проект
└── scripts/
└── trace_warnings.py ← разбор WARN/ERROR в трейсе Jaeger

В SKILL.md лежит то, что агенту нужно всегда: когда применять скилл, в каком порядке действовать, какие правила соблюдать, и пример. Развёрнутые форматы, проверка текста перед отправкой и настройки под конкретный проект вынесены в references. Механическую работу, разбор предупреждений и ошибок в трейсе, делает скрипт из папки scripts.

Что класть в SKILL.md скилла Claude по новым правилам Anthropic

Anthropic рекомендует держать основной SKILL.md короче 500 строк. Всё, что не помещается, разносят по отдельным файлам и ставят на них ссылки прямо из SKILL.md, как в структуре выше.

Поэтому ссылки держат на одном уровне вложенности, и все справочные файлы подключаются из SKILL.md напрямую. Если справочный файл длинный, в его начало ставят короткое оглавление. Оно сообщает агенту, что внутри, до того как тот потратит токены на чтение всего файла.

Ещё два правила касаются содержания. Первое – не объясняйте модели очевидное. Абзац о том, что такое счёт, в скилле для работы со счетами только съедает место и токены, ведь это Claude знает и без вас. В скилл кладут другое. Например, внутренние правила компании, которых модель знать не может.

Второе – описание скилла пишут в третьем лице, ведь именно по нему Claude решает, какой скилл взять. Формулировка «скилл создаёт счета клиентам и отправляет напоминания об оплате» работает, а «я помогу со счетами и напоминаниями» – нет. В описании должны стоять конкретные действия и те фразы, на которые скилл должен срабатывать.

Степени свободы и проверка на моделях 5.5

Не каждый шаг нужно расписывать одинаково подробно. Anthropic называет это степенями свободы. Рискованному шагу нужны детальные инструкции и ограничения, а там, где последствия небольшие, модели можно оставить простор для решения.

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

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

Ошибка агента в правило: цикл и формат

Скилл становится надёжным не в момент сборки, а по мере того, как в него попадают правила из реальных ошибок. Цикл состоит из четырёх шагов:

1. Поймать вывод агента, который расходится с реальностью.
2. Найти недостающую проверку.
3. Записать в скилл короткое правило вместе с историей его появления.
4. В следующей сессии агент сначала сверяется с этим правилом и только потом что-то утверждает о задаче.

В самом большом скилле конвейера, скилле тестирования задачи, таких правил набралось 19. Вот одно из них целиком.

6. Перед выводом BUG прочитай требование (спеку или код). Наблюдаемое поведение не баг, пока не доказано расхождение с требованием. Порядок: факт → требование → расхождение → BUG. Урок: деактивацию старой записи при совпадающей дате назвали BUG, не прочитав сервис, где это правило явно описано.

Формат стоит взять как шаблон. Правило сформулировано как проверка перед выводом и задаёт порядок рассуждения (факт, требование, расхождение, баг). Заканчивается оно уроком, то есть случаем, из-за которого появилось.

Ещё несколько ошибок, которые стали правилами:

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

Отдельный вопрос, кто пишет правило. Агенту можно поручить дописывать правила самому, и так действительно быстрее, но тогда он способен закрепить и неверный вывод. Поэтому правило лучше вносить после разбора человеком.

Чек-листы, петли проверки и хуки

Бывает, что правило в скилле есть, а агент всё равно его пропускает. На этот случай у Anthropic три инструмента разной жёсткости.

Для многошаговых задач в скилл кладут чек-лист, который Claude копирует в свой ответ и отмечает по ходу работы. Для задач с проверяемым результатом подходит петля обратной связи. Агент выполняет скилл, исправляет всё, что не прошло проверку, и повторяет, пока проверка не пройдёт. А если правило должно соблюдаться всегда и Claude его всё-таки иногда пропускает, его переносят из скилла в хук, то есть в код, который Claude Code запускает сам.

Хорошие кандидаты на жёсткость – правила, которые не зависят от стека. В QA-конвейере их набор такой:

• сначала план, и к проверкам на стенде агент приступает только с разрешения человека
• трекер и TMS – только с явного согласия
• после работы агент убирает за собой, а потом ещё и доказывает, что стенд остался чистым
• негативные проверки идут только в паре с позитивными
• для вывода «этого нет» нужно больше доказательств, чем для «это есть»
• к каждому багу прилагается оценка масштаба
• любое недоказанное утверждение агент отмечает как гипотезу

Как установить скилл в Claude всей команде

Скилл, который работает у вас, не обязательно заработает у коллег. Anthropic советует не ограничиваться указанием «используй такую-то библиотеку», а включать в сам скилл инструкции по установке нужных пакетов.

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

Для конвейера, где правило появляется после каждой разобранной ошибки, это особенно важно. С жёстким номером версии новое правило так и останется в вашей копии.

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

• Скилл (skill) Claude Code – Папка с файлом SKILL.md и вспомогательными файлами, которую агент подгружает, только когда запрос совпадает с описанием скилла.
• Прогрессивное раскрытие – Принцип, при котором SKILL.md работает как оглавление, а подробные файлы Claude открывает только на нужном шаге.
• Степени свободы – Уровень жёсткости инструкций в скилле: от свободного описания задачи до точного скрипта для рискованных шагов.
• Хук – Код, который Claude Code запускает сам в заданный момент, например перед командой, независимо от того, следует ли модель скиллу.
• Петля обратной связи – Паттерн, при котором скилл проверяет свой результат, исправляет ошибки и повторяет проверку, пока всё не пройдёт.
• Маркетплейс плагинов – Репозиторий, из которого команда устанавливает плагины Claude Code со скиллами и получает их обновления.

Итог: с чего начать завтра

• Выберите одну просьбу, которую объясняете агенту чаще всего.
• Соберите из неё скилл через /skill-creator и проверьте его на модели, с которой работаете.
• Держите SKILL.md короче 500 строк, справочники подключайте на одном уровне, длинным файлам добавьте оглавление.
• Напишите описание в третьем лице, с конкретными действиями.
• Следующую ошибку агента разберите сами и запишите правилом с уроком.

Проверьте себя

1. Вы хотите, чтобы агент знал порядок деплоя, но нужен он раз в неделю. Куда его положить?

• А. В CLAUDE.md, чтобы агент точно видел его всегда
• Б. В отдельный скилл деплоя с понятным описанием и триггерными фразами
• В. В промпт в заметках и копировать по необходимости

2. Ваш SKILL.md ссылается на reference-файл, а тот на ещё один длинный файл с ключевыми правилами. В чём риск?

• А. Никакого: Claude всегда читает все связанные файлы целиком
• Б. Claude может просмотреть только первые 100 строк третьего файла, и правила из конца он не увидит
• В. Скилл перестанет запускаться по триггерным фразам

3. Агент назвал багом поведение, которое явно описано в коде сервиса. Как правильно закрепить урок?

• А. Позволить агенту самому записывать уроки после каждой сессии
• Б. Самому разобрать, какой проверки не хватило, и дописать в скилл короткое правило с историей ошибки
• В. Просто поправить агента в чате текущей сессии

4. Правило «никогда не деплоить на prod» агент иногда нарушает, хотя оно написано в скилле. Что делать?

• А. Перенести проверку в хук, который Claude Code запускает сам перед командой
• Б. Написать правило в скилле капслоком
• В. Переписать правило подробнее и повторить его три раза

5. Вы перешли на модели 5.5, а старые скиллы стали выдавать результат хуже. Что проверить первым?

• А. Добавить в скилл объяснения базовых понятий
• Б. Объединить все скиллы в один большой файл
• В. Не слишком ли скилл предписывающий: убрать лишние инструкции там, где шаг не рискованный