С чего начать, если Agent Skill не срабатывает?
Сначала определите точный симптом: клиент не видит навык, видит его, но не выбирает автоматически, или выбирает, но не может выполнить шаги. Эти три сбоя происходят на разных этапах и требуют разных исправлений.
Наличие папки ещё не доказывает, что агент обнаружил её, прочитал метаданные и решил применить полную инструкцию. Если менять description до проверки пути или отлаживать Python до подтверждения активации, причина останется скрытой.
| Симптом | Что проверять первым |
|---|---|
| Навыка нет в списке | Путь, имя SKILL.md, YAML и перезапуск клиента |
| В списке есть, автоматически не включается | Description, политика неявного вызова и тестовый запрос |
| Включается, но задача падает | Инструкция, команда, runtime, зависимости и разрешения |
Как проверить обнаружение папки и SKILL.md?
Сверьте путь с документацией именно вашего клиента, убедитесь, что в отдельной папке лежит файл с точным именем SKILL.md, а frontmatter читается как YAML. После создания нового каталога перезапустите клиент.
- Проверьте область установки: личная, проектная, управляемая или plugin.
- Уберите лишний уровень вложенности и ошибочный файл вида skill-name.md.
- Проверьте обязательные name и description, кавычки, отступы и разделители YAML.
- Откройте список доступных skills или диагностическую команду клиента.
- Если каталог создан во время текущей сессии, перезапустите её.
Если навык ещё только подключается, пройдите отдельный порядок установки Agent Skills в Codex и Claude Code.
Зачем проверять навык явным вызовом?
Явный вызов — диагностический тест. Если он работает, обнаружение и загрузка, вероятно, исправны, а искать нужно в автоматическом выборе. Если не работает, сначала чините структуру или настройки.
Способ явного вызова зависит от клиента: это может быть команда, упоминание навыка или выбор из интерфейса. Не считайте ручной запуск постоянным решением — он лишь отделяет проблему discovery от проблемы triggering.
Почему description не приводит к автоматическому выбору?
Агент сопоставляет запрос с коротким описанием навыка. Description должен на языке пользователя назвать результат и условия применения; слишком узкая формулировка пропускает нужные запросы, а слишком широкая конкурирует с другими skills.
- Возьмите пять реальных формулировок задачи, а не внутреннее название процесса.
- Назовите наблюдаемый результат и момент, когда skill нужен.
- Уберите общие обещания вроде «помогает с разработкой».
- Разведите пересекающиеся skills по входам, результатам и границам.
- Добавьте близкие отрицательные запросы, где навык включаться не должен.
Подробная формула и набор тестов есть в материале как написать description в SKILL.md.
Какие настройки могут запретить автоматическую активацию?
Проверьте, не отключён ли skill и не разрешён ли ему только ручной вызов. После изменения конфигурации перезапустите клиент и повторите один и тот же тест в новой чистой сессии.
Названия полей различаются. OpenAI, Claude и GitHub по-разному задают доступность, ручной или модельный вызов и область загрузки. Не переносите фрагмент конфигурации одного хоста в другой без сверки с его документацией.
В большом каталоге часть описаний может быть сокращена или не попасть в стартовый список из-за бюджета контекста. Если новый skill появляется только после отключения лишних, проведите ревизию библиотеки, но не удаляйте всё по одному наблюдению.
Для системной очистки используйте ревизию Agent Skills.
Что делать, если skill активируется, но не выполняется?
Отделите текстовую инструкцию от внешнего действия. Проверьте точную команду, относительный путь, аргументы, runtime, зависимости, права на файлы и сеть, затем повторите запуск на тестовых данных.
- 1. Зафиксируйте последний успешный шаг
Подтвердите, что полный SKILL.md действительно был загружен.
- 2. Выполните команду отдельно
Запустите безопасный help или dry-run в той же среде.
- 3. Прочитайте stderr и exit code
Не заменяйте точную ошибку пересказом модели.
- 4. Проверьте ограничения среды
Сеть, shell, пакеты и запись файлов могут быть запрещены.
- 5. Повторите минимальный сценарий
Используйте фикстуру без секретов и необратимых действий.
Контракт исполняемой части разобран отдельно в статье Scripts в Agent Skill.
Как проверить автоматический выбор Agent Skill?
Составьте набор позитивных, негативных и пограничных запросов, запускайте их в чистых сессиях и записывайте: был ли skill выбран, какая версия загрузилась и выполнен ли критерий результата.
| Класс теста | Пример ожидаемого поведения |
|---|---|
| Позитивный | Реальная целевая задача активирует нужный skill |
| Негативный | Похожая, но чужая задача выполняется без него |
| Пограничный | Неясный запрос приводит к уточнению, а не случайной активации |
| Прямой | Явный вызов загружает именно проверяемую версию |
После проверки активации измерьте эффективность Agent Skill до и после: срабатывание само по себе не доказывает пользу.
Какой чек-лист пройти перед повторным запуском?
Навык готов к повторному тесту, если клиент видит правильный путь и версию, YAML валиден, явный вызов работает, description проходит позитивные и негативные запросы, а команды выполняются в доступной среде.
- Путь и область установки подтверждены.
- Имя SKILL.md и frontmatter проверены.
- Клиент перезапущен после изменения каталога или config.
- Ручной и автоматический вызов протестированы отдельно.
- Конфликты имён и пересечения description исключены.
- Runtime, зависимости и разрешения проверены.
- Результат подтверждён наблюдаемым артефактом или assertion.