Проверка Agent Skills Index (.well-known)

Что такое Agent Skills и зачем их проверять? Agent Skills

Agent Skills — инструкции для AI-агентов

Agent Skills — это небольшие Markdown-файлы (SKILL.md) с YAML frontmatter, дающие AI-агенту сфокусированные инструкции для работы с конкретным сайтом или сервисом. Файл навыка описывает: когда применять этот навык, как обращаться к API, какие соглашения соблюдать. Это принципиально отличается от MCP: если MCP даёт агенту инструменты с типизированными интерфейсами, то Agent Skills дают контекст и стратегию — «когда и как» вместо «что именно вызывать». Оба подхода дополняют друг друга.

Структура index.json и обязательные поля

Обнаружение навыков происходит через файл /.well-known/agent-skills/index.json. Инструмент проверяет: наличие файла, корректность JSON, поле $schema версии 0.2.0 (https://schemas.agentskills.io/discovery/0.2.0/schema.json), наличие обязательных полей каждого навыка (name, type, description, url, digest). Имя навыка — строчные буквы с дефисами, до 64 символов. Описание — до 1024 символов, на его основе агент решает, загружать ли навык.

SHA256-digest и проверка целостности

Каждый навык в index.json должен содержать поле digest в формате sha256:<hex> — хеш от сырых байт файла навыка. При каждом изменении SKILL.md хеш пересчитывается и обновляется в index.json. Это позволяет агентам без полной загрузки файла определить, изменился ли навык с прошлого визита. Несовпадение хеша с содержимым файла делает навык непроверяемым — клиенты вправе отклонить его. Инструмент проверяет корректность формата digest, но не пересчитывает хеш (это требует загрузки каждого файла).

CORS и поддержка браузерных агентов

Оба файла — index.json и каждый SKILL.md — должны возвращать заголовок Access-Control-Allow-Origin: *. Это необходимо для браузерных AI-агентов: расширений браузера, встроенных AI-ассистентов, которые запрашивают файлы напрямую из браузера пользователя. Без CORS браузерные агенты не смогут прочитать навыки даже если URL правильный. Убедитесь, что CORS-заголовок присутствует для пути /.well-known/ — многие серверные конфигурации не добавляют его для этого специального пути. Для более глубокой интеграции с AI-агентами рассмотрите также MCP Server Card — он даёт агентам типизированные инструменты для работы с вашим сервисом.

Развернуть все

Часто задаваемые вопросы

Чем Agent Skills отличается от MCP?

MCP — типизированные инструменты с JSON-RPC интерфейсом («что вызывать»). Agent Skills — Markdown-инструкции («как и когда»): контекст применения, соглашения, стратегия. Оба подхода дополняют друг друга.

Почему SHA256 обязателен в index.json?

Это контрольная сумма файла навыка. Агент сравнивает digest с содержимым файла и понимает, изменился ли навык без полной загрузки. Несовпадение делает файл непроверяемым — клиенты вправе его отклонить.

Для чего нужны CORS-заголовки в Agent Skills?

Браузерные AI-агенты (расширения, встроенные ассистенты) запрашивают файлы напрямую из браузера. Без Access-Control-Allow-Origin: * браузер блокирует запрос политикой same-origin — агент не получит навык.

Версия $schema 0.2.0 — это важно указывать?

Да. Без явного $schema клиенты откатываются к v0.1.0 со старым форматом полей. Версия указывает парсеру, какой синтаксис ожидать. При выходе v0.3.0 потребуется обновление поля.