Что означает поле compatibility?
Это необязательное поле frontmatter до 500 символов для специфических требований среды: целевого продукта, системных пакетов, версии runtime или доступа к сети. Большинству простых текстовых skills оно не требуется.
Compatibility помогает отсеять заведомо неподходящую среду до загрузки инструкции. Оно не проверяет наличие зависимости, не выдаёт разрешение и не доказывает, что автор тестировал каждую комбинацию. Исполняемые предусловия всё равно должен проверять setup или validator.
Когда compatibility нужно добавлять?
Добавляйте поле, если без конкретного клиента, пакета, runtime, ОС или сети skill не может выполнить основной сценарий. Если требование относится только к одной дополнительной ветке, опишите его рядом с этой веткой.
- Skill использует расширение frontmatter конкретного клиента.
- Script требует Python, Node.js, Docker, jq или другой пакет.
- Работа возможна только с сетью или определённым API.
- Нужна графическая сессия, browser automation или системная утилита.
- Поддержана только часть ОС или архитектур.
- Нужен MCP-сервер, connector или конкретный tool.
Не записывайте в compatibility пожелания к качеству результата и длинную инструкцию установки. Поле должно быстро ответить «может ли эта среда запустить основной путь?».
Что именно писать в compatibility?
Назовите минимальные измеримые требования: продукт или класс клиентов, runtime с версией, системные пакеты, сеть и особое разрешение. Не используйте расплывчатые слова «современный», «обычный» и «полностью совместим».
| Слабая формулировка | Проверяемая формулировка |
|---|---|
| Работает в AI-агентах | Requires an Agent Skills client that can run bundled Python scripts |
| Нужен Python | Requires Python 3.12+; tested with 3.12 and 3.13 |
| Нужен интернет | Requires HTTPS access to api.example.com for the publish step |
| Для Claude | Designed for Claude Code hooks; core SKILL.md remains standard |
| Cross-platform | Tested on Windows 11, macOS 15 and Ubuntu 24.04 |
Если точные версии делают строку слишком длинной, оставьте в frontmatter минимальный барьер, а проверенную матрицу и дату — в README или отдельном reference.
Где хранить остальные сведения о совместимости?
Разделите короткое требование, подробную матрицу и исполняемую проверку. Эти слои отвечают соответственно за обнаружение, решение пользователя и фактический запуск.
| Слой | Содержимое |
|---|---|
| SKILL.md frontmatter | Критическое минимальное требование до 500 символов |
| README / reference | Матрица клиентов, ОС, runtime, tested date и известные ограничения |
| setup / validator | Фактическая проверка команды, версии, сети и разрешения |
| CI | Регулярный прогон поддерживаемых комбинаций |
| Release notes | Изменения поддержки и миграция между версиями |
Как составить матрицу совместимости?
Строкой делайте реальную среду, столбцами — основной сценарий, scripts, дополнительные возможности и дату теста. Используйте статусы «проверено», «условно», «не поддерживается» и «не проверено».
- 1. Выберите основной сценарий
Один реальный запрос и fixture, одинаковые для всех клиентов.
- 2. Зафиксируйте среду
Клиент и версия, ОС, runtime, модель, tools и режим разрешений.
- 3. Проверьте discovery и execution
Клиент должен увидеть skill, активировать его и завершить основной путь.
- 4. Проверьте ограниченную ветку
Что происходит без сети, shell, дополнительного tool или client-specific поля.
- 5. Сохраните дату и evidence
Ссылка на run, ожидаемый результат и известное отличие от других сред.
Для одинакового сравнения сред примените протокол из статьи как тестировать Agent Skill.
Как обращаться с полями конкретного клиента?
Отделяйте открытый стандарт от расширений клиента. Базовый name, description и инструкция остаются переносимым ядром, а invocation control, hooks или другие расширения требуют явной совместимости.
Клиент может игнорировать неизвестное поле, отклонить файл или интерпретировать возможность иначе. Поэтому наличие расширения нужно проверять в каждом целевом клиенте, а критическую логику нельзя прятать только в необязательном поле без fallback.
- Помечайте расширение названием продукта и минимальной версией.
- Объясняйте, что теряется при игнорировании поля.
- Не копируйте один client-specific блок в универсальный пример без оговорки.
- Держите опасные действия за policy и подтверждением, а не за текстовым обещанием compatibility.
Архитектура переносимого ядра и адаптеров разобрана в материале один Agent Skill для Codex, Claude Code и Copilot.
Что делать, если требование не выполнено?
Остановиться до изменения состояния, назвать отсутствующее требование и предложить безопасный путь: установить зависимость, выбрать поддерживаемый режим или выполнить только текстовую часть без внешнего действия.
| Проблема | Корректное поведение |
|---|---|
| Нет runtime | Показать требуемую версию и команду диагностики; не запускать случайный интерпретатор |
| Нет сети | Сохранить локальный черновик; не объявлять публикацию успешной |
| Нет tool | Остановить зависимый шаг и вернуть список доступных альтернатив |
| Неизвестный клиент | Разрешить только базовый сценарий после smoke-теста |
| Недостаточно прав | Запросить минимальное конкретное разрешение, не весь shell или аккаунт |
Чек-лист честной совместимости
Хорошая декларация коротка, проверяема, привязана к версии и не смешивает требование с результатом теста.
- В compatibility указаны только критические требования.
- Версии и сетевые нужды сформулированы конкретно.
- Подробная матрица имеет дату проверки.
- Не проверено не выдано за не поддерживается — и наоборот.
- Client-specific расширения отделены от открытого стандарта.
- Есть безопасный отказ при отсутствующей зависимости.
- CI повторяет заявленные комбинации.
- Матрица пересматривается после обновления skill, клиента или runtime.