Agent Skills: реестр задач вашего агента

Что это

Agent Skills — машиночитаемый индекс конкретных навыков агента по адресу /.well-known/agent-skills/index.json. Каждый skill — это задача с описанием и ссылкой на детальный SKILL.md. В отличие от OpenAPI (endpoints) и MCP Tools (инструменты с JSON Schema), Skills описывают задачи на естественном языке — в терминах, понятных LLM-оркестратору.

Зачем это AI-агентам

Прежде чем делегировать задачу, оркестратор должен знать, что именно агент умеет. Skills — это машиночитаемый контракт: «вот список того, что я решаю». Без него выбор агента возможен только вручную. Это уровень выше, чем API: не «какие у тебя ручки», а «какие задачи ты закрываешь».

Минимальный рабочий пример

Индекс /.well-known/agent-skills/index.json:

[
  {
    "name": "scan-url",
    "type": "skill",
    "description": "Scan a public URL and return an agent-readiness score with a per-check breakdown",
    "url": "https://example.com/.well-known/agent-skills/scan-url.md",
    "sha256": "a3f8c2d1..."
  }
]

Для каждого skill публикуется SKILL.md (по url) с входными данными, результатом и примерами вызова. Content-Type: text/markdown.

Правильно vs неправильно

Правильно	Неправильно
Индекс по /.well-known/agent-skills/index.json	Произвольный путь
Каждый skill: name, type, description, url, sha256	Пропущены обязательные поля
url ведёт на реальный доступный SKILL.md	Битая ссылка на skill-файл
sha256 соответствует содержимому SKILL.md	Несовпадающий хеш — клиент не доверяет

Типичные ошибки

• Не массив на верхнем уровне или невалидный JSON.
• Пропущен sha256/url — оркестратор не может верифицировать/загрузить skill.
• SKILL.md недоступен (404) по указанному url.
• Skills не продублированы в A2A Agent Card — часть оркестраторов читает их оттуда.

Как проверить

Сканер делает GET на /.well-known/agent-skills/index.json, проверяет, что это массив с полями name/type/description/url/sha256, и HEAD-запросом — доступность первого url. Вручную:

curl -s https://example.com/.well-known/agent-skills/index.json | jq .