Устранение неполадок со skills

⏱️ Примерное время: ~12 минут · 🎯 Урок 6 курса «Введение в Agent Skills» · 🎬 видео

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

С чего начать

Начните с инструмента-валидатора skills (команда verifier для agent skills; проще всего установить через uv) — он первым делом выявляет структурные проблемы. Это самый быстрый способ отсеять очевидные ошибки до того, как вы перейдёте к более тонкой диагностике.

Частые проблемы и их решения

Skill не срабатывает

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

Skill не загружается

Файл SKILL.md должен находиться внутри именованной директории (а не в корне каталога skills) и называться строго SKILL.md (заглавными SKILL, строчными md). Запустите claude --debug, чтобы увидеть ошибки загрузки.

Используется не тот skill

Описания слишком похожи друг на друга — сделайте их различимыми и конкретными.

Конфликты приоритетов skills

Корпоративный (enterprise) или иной skill с более высоким приоритетом и тем же именем побеждает — переименуйте свой skill или обратитесь к администратору.

Skills из плагинов не появляются

Очистите кэш, перезапустите, переустановите. Если skill всё ещё отсутствует, возможно, неверна структура плагина (используйте валидатор).

Ошибки во время выполнения (runtime)

• Отсутствующие зависимости — установите их и укажите в Описании.
• Проблемы с правами доступа — выполните chmod +x для скриптов.
• Разделители путей — везде используйте прямые слеши (/), даже в Windows.

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

*Адаптировано с русским переводом. Оригинал: © 2025 Anthropic. All rights reserved.*