Как проверять Agent Skills в CI: структура, ссылки и тесты

Что именно может проверить CI у Agent Skill?

CI может проверить формат пакета, существование ссылок, тесты скриптов и заранее подготовленные сценарии поведения. Эти проверки отвечают на разные вопросы, поэтому их нельзя сводить к одной команде или одному среднему баллу.

Проверка начинается с простого: каталог существует, SKILL.md читается, обязательные поля заполнены, относительные пути ведут к реальным файлам. Затем отдельно проверяются scripts и зависимости. Поведенческий контур запускает навык на типовых, нерелевантных и пограничных запросах.

Если сначала нужно понять, как измерять результат на одинаковых задачах, используйте материал как оценить эффективность Agent Skill. В этой статье фокус уже: автоматический gate для изменения в репозитории.

Почему одной проверки SKILL.md недостаточно?

Валидный SKILL.md доказывает, что файл соответствует базовым правилам формата. Он не доказывает, что ссылки рабочие, скрипты корректны, навык выбирается для нужных запросов и не ухудшает работу соседних навыков.

Спецификация рекомендует команду skills-ref validate для проверки соглашений формата. README самого проекта называет библиотеку демонстрационной. Значит, её результат полезен как первый фильтр, но не как знак готовности к production.

Какие статические проверки запускать на каждом pull request?

На каждом pull request проверяйте изменённые каталоги skills, frontmatter, прямые ссылки, переносимость путей, scripts, зависимости и признаки опасных действий. Этот job должен работать без рабочих секретов и без права записи.

1. 1. Найдите изменённые skills

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

2. 2. Проверьте формат

   Запустите skills-ref validate для каждого изменённого каталога и сохраните полный вывод.

3. 3. Проверьте ссылки

   Убедитесь, что каждый локальный путь из SKILL.md существует и остаётся внутри пакета.

4. 4. Проверьте scripts

   Запустите lint, unit-тесты, отрицательные входы и проверку кодов завершения.

5. 5. Проверьте границы

   Найдите сеть, shell-команды, broad glob, secrets, hooks и MCP-ссылки, которые меняют профиль риска.

Как проверять references, assets и scripts?

CI должен подтвердить существование файлов, корректность относительных путей и отдельный контракт каждого типа ресурса. References читаются по условию, assets используются для результата, а scripts выполняются и требуют собственных тестов.

• Запрещайте абсолютные и машинно-зависимые пути в переносимых пакетах.
• Проверяйте Markdown-ссылки и отсутствие цепочек, которые уводят к несуществующему файлу.
• Проверяйте, что scripts имеют неинтерактивный интерфейс, понятные ошибки и заявленные зависимости.
• Не исполняйте непроверенный script на постоянном self-hosted runner с рабочими данными.
• Фиксируйте lockfile или другой воспроизводимый способ получить зависимости.

Практическое разделение содержимого описано отдельно: как разделить большой SKILL.md.

Чем поведенческие тесты отличаются от валидации формата?

Поведенческий тест запускает агента и проверяет выбор навыка, обязательные шаги, ограничения и конечный результат. Валидация формата читает пакет как данные и не видит, как модель применит инструкции в реальной сессии.

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

• Сработал для ожидаемого запроса.
• Не сработал для отрицательного запроса.
• Выполнил обязательные шаги и остановился на запрете.
• Вернул проверяемый результат.
• Не добавил неожиданные tool calls, сеть или изменения файлов.

Как проектировать условия срабатывания, разобрано в статье про description в SKILL.md.

Как разделить jobs без секретов и с учётными данными?

Сначала выполняйте полностью локальный job без секретов. Модельные evals с учётными данными запускайте только после статического gate в изолированной доверенной среде; код из внешнего pull request не должен получать рабочие токены.

GitHub Actions позволяет задать permissions: contents: read и обнулить остальные права. Для внешнего кода опасно сочетать pull_request_target, checkout ветки автора и секреты. Если eval невозможно провести безопасно в PR, запускайте его вручную или после merge в отдельном окружении.

Какие проверки сделать обязательными перед merge?

Обязательными стоит сделать быстрый package-check и основной eval-набор. Изменения scripts, hooks, MCP, сети, прав и доставки требуют дополнительного человеческого ревью, даже если автоматические jobs зелёные.

• agent-skills / package: формат, пути, scripts и зависимости.
• agent-skills / evals: срабатывание, обязательные шаги и результат.
• security review: отдельное подтверждение для расширения доступа или необратимых действий.
• Уникальные стабильные имена jobs, чтобы protected branch ожидала правильный статус.

Критический провал нельзя компенсировать хорошим средним баллом. Если навык выполнил запрещённое действие или отправил данные не туда, такой сценарий блокирует выпуск независимо от остальных результатов.

Что сохранять в отчёте CI?

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

• Точная версия пакета и hash изменения.
• Клиент, модель, режим, разрешения и среда.
• Входные сценарии и ожидаемые критерии.
• Фактический результат и tool trace после очистки.
• Причина каждого незачёта и сравнение с baseline.

Workflow artifact удобен для разбора, но срок хранения и доступ к нему нужно ограничить. Маскирование секрета в логе не заменяет очистку результата: преобразованные или частично выведенные значения могут не совпасть с маской.

Когда автоматической проверки мало?

Человек нужен, когда меняется назначение навыка, расширяются права, добавляются сеть, shell, hooks, MCP или необратимые действия. Автоматический тест проверяет заранее описанные правила и не принимает новое продуктовое решение за владельца процесса.

Отдельно рассматривайте изменение trust boundary. Новый внешний домен, broad filesystem scope или команда публикации могут не нарушить синтаксис и пройти старый eval, но заметно увеличить последствия ошибки.

Перед первым подключением стороннего пакета пройдите чек-лист проверки AI-навыка. CI поддерживает уже принятый стандарт, а не заменяет исходный аудит.

Как внедрить CI для skills без большого проекта?

Начните с одного репозитория, одного skill и двух jobs. Сначала сделайте package-check обязательным, затем перенесите три уже используемых сценария в eval-набор и добавляйте новый тест после каждого реального провала.

1. 1. Зафиксируйте стандарт пакета

   Опишите допустимые пути, зависимости и условия ручного ревью.

2. 2. Добавьте быстрый job

   Проверьте формат, ссылки и scripts без секретов.

3. 3. Перенесите три сценария

   Возьмите прямой, отрицательный и пограничный запрос из реальной работы.

4. 4. Включите required checks

   Запретите merge при критическом провале.

5. 5. Расширяйте по фактам

   Каждая найденная ошибка становится новым тестом или правилом ревью.

Если нужен единый контур для нескольких навыков, моделей и команд, Скилловик может помочь спроектировать пилот, автоматические gates и понятный выпуск без подключения к рабочим данным на первом шаге.