Почему артефакт молчит

Молчащий скилл переписывают наугад, а причин всего три, и они лежат на разных слоях: артефакт не найден, артефакт не выбран, артефакт загружен, но не влияет. Диагностика начинается с определения слоя, а не с правки текста.

Слой 1: не найден

Первый вопрос — видит ли его агент вообще. Спросите прямо: «какие скиллы доступны?». Если в списке нет — проблема здесь.

• Сломанный frontmatter. Если YAML не разбирается, Claude Code грузит тело скилла с пустыми метаданными: /имя работает, а описания, по которому агент мог бы сопоставить запрос, нет. Симптом коварный — вручную скилл вызывается, сам не срабатывает никогда. Ищите такие файлы командой claude plugin validate .claude/skills (и ~/.claude/skills для личных), а причину разбора покажет запуск с --debug.
• Frontmatter не с первой строки. Открывающие --- обязаны быть первой строкой файла. Иначе весь файл, вместе с маркерами, считается содержимым.
• Вложенный каталог. Скиллы из .claude/skills/ в подкаталогах не грузятся при старте: они появляются, когда агент впервые прочитает файл в этом подкаталоге.
• Новый каталог верхнего уровня. Живое отслеживание изменений работает для файлов внутри уже существующих каталогов скиллов. Если вы создали сам каталог после старта сессии — перезапустите.
• Каталог добавлен через --add-dir. Скиллы и команды оттуда грузятся (это исключение из общего правила), но только если источник настроек project включён.

Живое отслеживание, кстати, покрывает только текст SKILL.md. Изменения в hooks/, .mcp.json, agents/ внутри плагина требуют /reload-plugins (Раздача артефактов).

Слой 2: не выбран

Скилл в списке, но агент его не берёт.

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

Вторая причина неочевидна совсем. Перечень скиллов имеет бюджет символов — примерно 1% контекстного окна модели. Имена в перечне остаются всегда, а вот описания при переполнении обрезаются, начиная с наименее используемых скиллов. То есть ваш редкий скилл может потерять ровно те ключевые слова, по которым его должны были найти.

Что с этим делать:

• /doctor покажет оценку стоимости перечня и его крупнейших вкладчиков;
• строка Skills в /context показывает размер перечня уже после применения бюджета — то есть то, что реально видит модель (Котёл);
• бюджет поднимается настройкой skillListingBudgetFraction (например, 0.02 — 2%) или переменной SLASH_COMMAND_TOOL_CHAR_BUDGET;
• освободить бюджет можно, переведя малоприоритетные скиллы в состояние name-only через skillOverrides;
• предел на одну запись — 1536 символов на description плюс when_to_use, и он не зависит от общего бюджета.

Состояния skillOverrides — четыре, и они решают большинство вопросов «покажи это агенту, но убери из моего меню» и наоборот:

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

Слой 3: загружен, но не влияет

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

1. усилить description и сами инструкции, чтобы модель продолжала их предпочитать;
2. вспомнить, что тело скилла входит в разговор один раз и заново не перечитывается: указания должны быть сформулированы как постоянные, а не как одноразовые шаги;
3. если поведение обязано соблюдаться всегда — переносить его в хук, который выполняется независимо от решения модели (Стражи).

Отдельный случай — после сжатия контекста. Тела вызванных скиллов вставляются обратно с ограничением 5000 токенов на скилл и 25 000 суммарно, и старые вылетают первыми. Если вы за сессию вызвали много скиллов, нужный мог выпасть целиком: просто вызовите его снова.

Обратная задача: срабатывает слишком часто

Лечится двумя движениями: сузить описание и, если вызов должен быть ручным, поставить disable-model-invocation: true. Это же убирает описание из контекста целиком — приятный побочный эффект для бюджета перечня. Устройство полей — Устройство артефакта.