Claude Code 5 раз проигнорировал мой skill. 1 строка всё исправила

Скилл в Claude Code может отлично работать, когда вы вызываете его по имени, и при этом ни разу не загрузиться сам. Наш запускался каждый раз, когда мы набирали его имя, и пропускался каждый раз, когда мы просили о той же задаче обычными словами. Мы увидели, как его пропускают, прочитали почему и переписали одну строку, которая всё исправила.

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

Тест (тот же запрос, свежие сессии)	Скилл загружен
Вызов по имени (/release-notes)	2 из 2
Обычные слова, исходное описание	0 из 5
Обычные слова, переписанное описание	5 из 5

Скилл - это папка с одним файлом внутри, SKILL.md. Файл начинается с короткого заголовка (имя и описание одним предложением), дальше идут инструкции. Он работает как функция: вызывающий читает сигнатуру и докстринг, а тело выполняется, только когда функцию вызывают. Положите его в домашнюю папку, чтобы он был в каждом проекте, или в репозиторий, чтобы он достался всем, кто там работает.

Начинайте с задачи, а не с файла. Возьмите промпт, который вы вечно набираете заново, и запишите, какой именно результат вам нужен. У нас это были еженедельные release notes: коммиты с понедельника, сгруппированные по областям, без рутины, по одной строке на изменение с номером pull request. На open-source репозитории Hono этот длинный промпт дал чистые заметки по восьми исправлениям ошибок за неделю, и этот результат стал целью для скилла.

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

Создайте в проекте .claude/skills/release-notes/SKILL.md: папка skills внутри скрытой папки .claude, папка с именем скилла и файл скилла внутри неё. Папка важна. Одиночный release-notes.md не загружается вообще, и документация называет это первым, что нужно проверить.

Заголовок - это несколько строк с метками между двумя рядами дефисов, и он должен начинаться с первой строки файла, иначе Claude Code его игнорирует. У нас было имя release-notes и описание, которое написало бы большинство людей:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Под заголовком идут инструкции в виде пронумерованных шагов, такие же, какие вы дали бы новому коллеге. У нас их пять: найти коммиты с понедельника, отбросить коммиты chore и docs, сгруппировать по scope из conventional commits, написать одну простую строку на изменение и вывести блок с заголовком и короткой сводкой сверху. Anthropic советует держать эту часть короткой. Перезапуск не нужен: Claude Code подхватывает новый или изменённый скилл в уже открытой сессии.

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

Коллега не станет набирать имя скилла. Он откроет новую сессию и попросит так, как попросил бы вас. Вот это и проверьте: откройте свежую сессию (новый разговор, в котором ничего не загружено) и попросите задачу своими словами. Сессия обязательно должна быть свежей: уже использованный скилл остаётся в разговоре, и тест в такой сессии ничего не доказывает.

Мы набрали "what did we ship this week?". Claude сам запустил лог коммитов и написал сводку по-своему, без малейших следов скилла. Ответы были неплохие, но от запуска к запуску плавали: один считал с понедельника, другой от последнего тега релиза и притянул изменение в документации, которое скилл бы отбросил. В пяти свежих сессиях скилл был пропущен во всех пяти.

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

Прежде чем менять хоть слово, сделайте три проверки:

1. /skills показывает все скиллы, которые видит сессия. Найдите свой. Наш был в списке и включён, но в окружении было 277 скиллов, и несколько скиллов из плагинов совпадали со словом "release" раньше нашего.
2. claude --debug пишет подробный лог того, что загружает Claude Code. Посмотрите строки про скиллы. У нас проектный скилл был загружен, и там же было предупреждение, что список скиллов превышает бюджет, поэтому часть описаний обрезается.
3. claude plugin validate .claude/skills проверяет, что заголовок составлен правильно. Это важно: сломанный заголовок всё ещё позволяет запускать скилл по имени, но Claude больше не может сопоставить его сам. Наш проверку прошёл.

Проверка	Что она показывает	Наш результат
/skills	Виден ли скилл и включён ли он?	В списке, включён (277 скиллов)
--debug	Загрузился ли он? Обрезан ли список?	Загружен; предупреждение о превышении бюджета
plugin validate	Разбирается ли заголовок?	Пройдено

Когда файл загружен и заголовок корректен, причина в описании. Пока Claude не решил загрузить скилл, он не читает ваши инструкции. Он читает по одной строке на скилл, имя и описание, и сопоставляет их с вашими словами. Наше гласило "generates changelog documents from repository history", а запрос звучал "what did we ship this week". В этих двух предложениях нет ни одного общего слова. Claude так и не прочитал наши инструкции; он прочитал одну строку, и в ней не было наших слов.

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

Пишите описание для момента, когда кто-то просит, а не для файла. Скажите, что скилл делает, когда его использовать и какие слова люди реально набирают. Наше превратилось в такое:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Руководство Anthropic по написанию добавляет одно правило: пишите в третьем лице ("Writes"), а не "I can help" и не "You can use this".

Затем проверьте в свежей сессии тем же запросом. "What did we ship this week?" теперь загружал скилл ещё до того, как Claude хоть что-то трогал, и заметки выходили в нашем формате в пяти свежих сессиях из пяти.

Сделайте и базовое сравнение: выключите скилл через skill override в локальном файле настроек (это скрывает скилл, не удаляя его). Когда он был выключен, Claude возвращался к своей сводке; когда включён, скилл загружался. Разницу сделал именно скилл, а не случайность.

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

Один запрос доказал исправление, но скилл, на который опирается команда, просят множеством способов. Skill-creator от Anthropic описывает тест: двадцать запросов, смесь тех, что должны загрузить скилл, и почти попаданий, которые не должны. Почти попадание звучит похоже, но это другая задача, например "write a commit message for my staged changes". Запускайте каждый запрос в отдельной свежей сессии и отмечайте, загрузился ли скилл. Собственный скрипт skill-creator не увидел скилл на нашей версии Claude Code, поэтому мы прогнали те же двадцать запросов собственным коротким скриптом.

Описание	Запросы, которые должны загрузить скилл и загрузили	Почти попадания, которые его загрузили
Исходное	4 из 10	0 из 10
Переписанное	10 из 10	0 из 10

До переписывания скилл загружали только запросы, где уже были слова "release notes", "changelog" или "release": то самое сопоставление по словам из шага четвёртого, на виду у всех. После переписывания он загрузился на каждый запрос, который должен был его загрузить, и по-прежнему не откликнулся ни на одно почти попадание.

Для скилла, который не должен промахиваться, используйте принуждение. Наберите его имя или добавьте хук (небольшой скрипт, который Claude Code запускает в определённый момент, здесь при каждом вашем сообщении), чей вывод велит Claude использовать скилл для этой задачи. С хуком даже исходное описание загрузило скилл на обычный запрос. Ограничение: каждый тестовый запуск тратит реальный лимит использования, а хук добавляет строку в каждое сообщение, так что оставьте его для немногих скиллов, которые действительно обязаны срабатывать. Перезапускайте свой список при каждом изменении описания.

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

Скилл окупается на задаче, которую вы повторяете с фиксированным результатом: еженедельные заметки, описание pull request, чек-лист релиза. Он не окупается на разовом вопросе и не подходит для правила, которое должно выполняться всегда: это работа хука. Куча неиспользуемых скиллов тоже обходится дорого, ведь когда их слишком много, Claude Code начинает обрезать описания, начиная с наименее используемых. Хорошее описание повышает шансы, но не заставит скилл срабатывать на задачу, для которой он не предназначен, а несколько запусков - это демо, так что настоящая проверка - ваш список тестовых запросов.

Главное правило: пишите описание теми словами, которые вы реально набираете, когда просите об этой задаче.