Почему навык не срабатывает

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

Навык не загрузился

В шапке SKILL.md два обязательных поля. Имя: до 64 символов, только строчные латинские буквы, цифры и дефисы, без слов anthropic и claude. Описание: непустое, до 1024 символов, без XML-тегов. Если поле нарушает правило, навык не появится в списке — и никакой ошибки вы можете не увидеть. По документации Anthropic, ноябрь 2026.

Лежит не там

В Claude Code навыки берут из ~/.claude/skills/ — личные, и .claude/skills/ — проектные, относительно корня репозитория. Файл должен называться SKILL.md и лежать в своей папке: skills/my-skill/SKILL.md, а не просто skills/SKILL.md.

Отдельная ловушка: кастомные навыки не синхронизируются между продуктами. Загруженный в claude.ai не появится в Claude Code и наоборот.

Описание не говорит, когда

Агент при запуске видит только имя и описание — примерно сто токенов на навык. По описанию он и решает, включать ли навык. Если там написано «помогает с документами», у агента нет повода выбрать именно этот навык.

Рабочее описание отвечает на два вопроса: что навык делает и в каких случаях его брать. Пример из документации: «Извлекает текст и таблицы из PDF, заполняет формы, объединяет документы. Использовать при работе с PDF, формами и извлечением текста».

Описание от первого лица

Документация просит писать в третьем лице. «Я помогу обработать таблицу» и «вы можете использовать это для таблиц» — хуже, чем «Обрабатывает таблицы и строит сводки. Использовать при работе с Excel и табличными данными». Описание попадает в системный промпт, и сбитое лицо мешает выбору.

Задача мимо описания

Агент ищет совпадение с вашими словами. Если описание говорит про «таблицы и .xlsx», а вы просите «посчитать выручку по кварталам», навык может не включиться. Это не баг: добавьте в описание слова, которыми вы реально называете задачу.

Слишком много похожих навыков

Каждый навык конкурирует за выбор. Десять навыков с описанием «работа с документами» — это лотерея. Держите описания разными: у каждого свой предмет и свои слова-триггеры.

Нет того, что нужно

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

В API, кроме того, нужен инструмент выполнения кода: без него контейнера с навыками нет.

Инструкция и ссылки

Тело SKILL.md держат короче 500 строк: после включения каждый токен конкурирует с историей разговора. Если файл больше — его разбивают, а из SKILL.md ссылаются на части.

Ссылки делают на один уровень: SKILL.md → reference.md. Если ссылка ведёт на файл, который ссылается на третий, агент может прочитать только начало через head -100 и не увидеть суть.

Мелочи, которые ломают запуск

Пути только с прямыми слэшами, даже на Windows: scripts/helper.py, а не scripts\helper.py. Если навык вызывает инструменты MCP, имя пишут полностью: GitHub:create_issue, иначе агент не найдёт инструмент. И не давайте десять равноправных вариантов — дайте один по умолчанию и запасной.

Как проверить за пять минут

Спросите агента, какие навыки он видит. Если нужного нет — проблема в шапке или пути.

Сформулируйте задачу словами из описания. Сработало — значит дело в формулировке, а не в навыке.

Упростите описание до одной понятной фразы «что делает» и «когда брать». Если заработало — дело было в описании.

Проверьте на второй модели: то, что понятно сильной модели, слабой может не хватить. Документация советует тестировать на всех моделях, с которыми планируете работать.

Короткий чек-лист

Имя по правилам и без запрещённых слов. Описание: что делает, когда брать, в третьем лице, с вашими словами. Файл лежит в ~/.claude/skills/ или .claude/skills/ и называется SKILL.md. Задача сформулирована близко к описанию. Нужные пакеты и сеть доступны в той среде, где работает агент. Тело короче 500 строк, ссылки на один уровень.

Если после этого не работает — скорее всего, дело не в навыке. Начните с вопроса «видит ли агент его вообще», а не с переписывания инструкции.