Модуль 1 · Навыки · урок 6 из 6

Диагностика проблем с навыками

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

Симптом 1. Навык не срабатывает автоматически

Самый частый. Вы просите «подготовь описание релиза», а Claude пишет что-то своё, не по шаблону.

Проверка 1: навык вообще виден? Спросите: «Какие навыки тебе доступны?» Если вашего нет в списке — проблема в пути или в файле, смотрите симптом 2. Если есть — читайте описание, которое Claude показал.

Проверка 2: описание есть и осмысленное? Если в списке навык без описания — сломана шапка. Claude Code при нечитаемом YAML загружает тело с пустыми метаданными: команда /имя работает, а сопоставлять с просьбой нечего. Причины: перед первым --- есть пустая строка или пробел; незакрытая кавычка; двоеточие внутри значения без кавычек (description: Навык: релиз-ноты — YAML прочитает это как ошибку). Проверить все навыки разом:

bash

claude plugin validate .claude/skills
claude plugin validate ~/.claude/skills

Команда покажет, какие файлы не разбираются и почему. Запуск с --debug тоже выводит ошибки разбора.

Проверка 3: работает ли ручной вызов? Наберите /release-notes 2.4. Если сработало — тело в порядке, проблема только в описании. Если нет — смотрите симптом 3.

Проверка 4: совпадает ли описание с просьбой? Перечитайте description глазами коллеги. Вы просили «описание релиза», а в описании только «релиз-ноты» и «changelog»? Добавьте недостающие формулировки. Поле when_to_use для этого и существует — туда можно вписать примеры реальных просьб.

Проверка 5: не выключен ли автоматический вызов? Поле disable-model-invocation: true убирает навык из контекста Claude: он о нём не знает и сработать не может. Это нормально для деплоя, но если вы поставили его случайно — уберите. То же делает skillOverrides в настройках со значением "user-invocable-only" или "off".

Проверка 6: не обрезано ли описание? Об этом — симптом 5.

Симптом 2. Навыка нет в списке

Значит, Claude Code его не нашёл. Проверьте по порядку:

Путь. Ровно .claude/skills/<имя>/SKILL.md. Не .claude/skill/, не skills/ в корне проекта, не SKILL.MD и не skill.md — имя файла в верхнем регистре с расширением в нижнем.
Папка, а не файл. .claude/skills/release-notes.md — не навык. Нужна папка release-notes/ с файлом внутри. Файл без папки работает только в .claude/commands/.
Проект. Навык лежит в .claude/skills/ того проекта, в котором вы запустили Claude Code? Если вы работаете из поддиректории или соседнего репозитория, Claude Code ищет в другом месте. Вложенные .claude/skills/ в поддиректориях подключаются только при работе с их файлами.
Плагин. Навык из плагина после установки может требовать /reload-plugins. Если плагин недавно менялся — тоже. Если плагинные навыки упорно не появляются, документация советует очистить кэш ~/.claude/plugins/cache и переустановить плагин.

Симптом 3. Навык срабатывает, но делает не то

Тело загрузилось, а результат не по шаблону.

Динамическая команда упала. Если в теле есть !`git log …` и команда завершилась с ошибкой, вызов навыка прерывается целиком — Claude текста не видит. Выполните команду руками в той же папке. Частая причина: git describe --tags в репозитории без тегов.
Инструкция расплывчата. «Оформи красиво» ничего не значит. Дайте шаблон и запреты, как в уроке «Создаём первый навык».
Аргумент не дошёл. В теле нет $ARGUMENTS, а вы передали версию? Claude Code допишет её в конец как ARGUMENTS: 2.4, но инструкция может её не учитывать. Вставьте плейсхолдер в нужное место.
Claude не открыл вспомогательный файл. Ссылка на checklist.md есть, но рядом не сказано, зачем он. Напишите: «прочитай критерии в checklist.md и пройди по ним каждый файл». Инструкция «прочитай» надёжнее, чем просто ссылка.
Изменения не подхватились. Проектные и личные навыки перечитываются при вызове. Плагинные — после /reload-plugins. Если вы правите навык, а результат прежний, проверьте, какой именно файл Claude загружает: при совпадении имён побеждает не тот, что вы редактируете (симптом 4).

Симптом 4. Конфликт имён

Два навыка с одним именем — и работает не тот. Порядок приоритета: организация выше личных, личные выше проектных. Личный ~/.claude/skills/release-notes/ перекроет проектный .claude/skills/release-notes/, и коллеги будут видеть один результат, а вы — другой. Плагинные навыки живут в своём пространстве имён (/плагин:навык) и не конфликтуют. Если в .claude/commands/ есть файл с тем же именем, что у навыка, побеждает навык.

Диагностика: спросите список навыков и посмотрите описание — оно подскажет, какой файл загружен. Лечение: переименуйте личный или удалите дубликат.

Симптом 5. Описание обрезано

Список навыков в контексте имеет бюджет — один процент контекстного окна модели. Имена попадают в список всегда, а описания при переполнении укорачиваются, начиная с навыков, которые вы вызываете реже всего. Обрезанное описание теряет ключевые слова, и навык перестаёт срабатывать, хотя вчера работал. Это случается, когда навыков накопилось много — свои плюс из нескольких плагинов.

Проверить: /context показывает строку Skills с реальным размером списка; /doctor оценивает стоимость списка и главных «потребителей». Ещё есть /skill-doctor — он показывает, какие навыки не используются и сколько стоят.

Лечение, от простого к сложному:

Сократите описания и поставьте главный сценарий в начало: на один навык действует лимит 1 536 символов вне зависимости от бюджета.
Отключите ненужные навыки через skillOverrides в настройках: "off" — выключить совсем, "name-only" — оставить в списке только имя.
Поднимите бюджет настройкой skillListingBudgetFraction, например до 0.02.

Симптом 6. Навык срабатывает слишком часто

Claude грузит навык проверки доступности, когда вы правите SQL. Причина — слишком общее описание: слово «проверь» есть в половине просьб. Сделайте описание конкретным («проверяет доступность разметки», а не «проверяет код»), добавьте paths с шаблоном файлов, к которым навык относится, или, если навык всё равно всегда вызываете сами, поставьте disable-model-invocation: true.

Симптом 7. Разрешения ведут себя не так

«Я указал allowed-tools, а Claude всё равно смог отредактировать файл». Правильно: allowed-tools — это предварительное одобрение перечисленных инструментов на один ход, а не ограничение остальных. Чтобы убрать инструменты, нужен disallowed-tools. И наоборот: «Claude спрашивает подтверждение на git log, хотя навык его разрешил» — грант действует только на ходу вызова навыка; на следующем вашем сообщении он сброшен. Вызовите навык снова.

Как проверять навык по-настоящему

Быстрая диагностика выше закрывает поломки. Но «навык не помогает» — тоже проблема, и её так не увидеть. Документация предлагает честный способ: сравнение с навыком и без. Соберите пять-шесть реальных просьб, прогоните каждую в свежей сессии с навыком, затем — с навыком, выключенным через skillOverrides: {"release-notes": "off"}. Если результаты не отличаются, навык не срабатывает или ничего не добавляет. Если с навыком хуже — инструкция мешает. Полчаса на такую проверку окупаются, когда навыком будет пользоваться вся команда.

Для системной оценки есть плагин skill-creator из официального маркетплейса: он гоняет навык по набору тестовых сценариев и сравнивает версии.

Попробуйте сами

10–15 мин на рабочем месте

Возьмите рабочий навык и последовательно сломайте его тремя способами: пустая строка перед ---, двоеточие в описании без кавычек, переименование SKILL.md в skill.md. После каждого запросите список навыков и запустите claude plugin validate. Запомните, как выглядит каждая поломка.
Выполните /context и найдите строку Skills. Сколько навыков у вас в списке и сколько они занимают? Есть ли те, что можно перевести в name-only?
Проведите сравнение с навыком и без для одного из своих навыков на трёх просьбах. Запишите, что изменилось.

Коротко

Начинайте с вопроса «какие навыки доступны?»: нет в списке — путь или файл; есть без описания — сломана шапка.
claude plugin validate .claude/skills находит нечитаемые шапки; --debug показывает ошибки разбора.
Работает /имя, но не автоматически — дорабатывайте description и when_to_use под реальные просьбы.
Упавшая команда !`…` прерывает вызов целиком; проверяйте её руками.
Совпадение имён: организация > личные > проектные; плагины — в своём пространстве имён.
Список навыков ограничен бюджетом; /context, /doctor, /skill-doctor и skillOverrides помогают его уместить.
Честная проверка — сравнение результатов с навыком и без него.

Видеоверсия

Сценарий озвучки · 556 слов, ≈ 4 мин

Навык — это текст. Когда он не работает, ошибки нет: Claude просто делает что-то другое. Это раздражает больше, чем упавшая сборка, потому что непонятно, куда смотреть. Сегодня — карта симптомов. Идите по ней сверху вниз.

Симптом первый, самый частый: навык не срабатывает автоматически. Вы просите описание релиза, а Claude пишет своё, не по шаблону. Первая проверка — навык вообще виден? Спросите: «какие навыки тебе доступны?» Нет в списке — проблема в пути или файле. Есть — читайте описание, которое Claude показал.

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

Дальше — работает ли ручной вызов? Наберите слэш и имя. Сработало — тело в порядке, дело в описании. Перечитайте его глазами коллеги. Вы просили «описание релиза», а в описании только «релиз-ноты»? Добавьте недостающие слова. Для примеров реальных просьб есть отдельное поле «когда использовать». И проверьте, не стоит ли случайно поле, отключающее вызов моделью, — с ним навык из контекста Claude убирается совсем.

Симптом второй: навыка нет в списке. Значит, Claude Code его не нашёл. Путь должен быть ровно: точка-клод, скиллс, папка с именем навыка, файл скилл-эм-дэ заглавными. Не файл без папки — это работает только в старой папке коммандс. И в том проекте, из которого вы запустили Claude Code. Навык из плагина после установки может требовать перезагрузки плагинов.

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

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

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

Симптом шестой: навык срабатывает слишком часто. Причина — слишком общее описание: слово «проверь» есть в половине просьб. Сделайте описание конкретным, добавьте поле «пути» с шаблоном файлов или переведите навык в только ручной режим.

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

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

Отметка хранится только в вашем браузере