Agent Skills

Что такое Agent Skills?

Agent Skills — структурированный список конкретных capabilities (навыков) AI-агента, публикуемый как индексный файл /.well-known/agent-skills/index.json. Каждый skill имеет ID, описание, входные/выходные типы. Позволяет оркестраторам выбрать нужного агента по задаче.

{
  "skills": [
    {
      "id": "scan-url",
      "name": "Scan URL for agent readiness",
      "description": "Given a URL, returns agent readiness score 0-100 with detailed checks",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["url"]
      }
    }
  ]
}

Зачем нужны Agent Skills?

Оркестратор должен знать, что именно умеет агент, прежде чем делегировать ему задачу. Agent Skills — машиночитаемый контракт между агентами.

В отличие от OpenAPI (описывает HTTP endpoints), Skills описывают высокоуровневые задачи в терминах, понятных LLM-оркестраторам в рамках Google Agent-to-Agent (A2A) Protocol.

Формат	Аудитория	Уровень описания
OpenAPI	HTTP-клиент	Endpoints, параметры, коды ответов
MCP Tools	MCP-клиент	Инструменты с JSON Schema
Agent Skills	LLM-оркестратор	Задачи на естественном языке + schema

Без Skills оркестратор не может автоматически выбрать агента — только через ручную конфигурацию.

Как реализовать Agent Skills?

1. Создайте индекс-файл /.well-known/agent-skills/index.json:

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

2. Опубликуйте SKILL.md для каждого навыка по URL из индекса. Файл описывает входные данные, ожидаемый результат, примеры вызова.

3. Добавьте skills в A2A Agent Card — оркестраторы, поддерживающие A2A, читают skills из /.well-known/agent.json.

Nginx — статическая публикация:

location ^~ /.well-known/agent-skills/ {
    alias /var/www/well-known/agent-skills/;
    add_header Content-Type application/json;
}

Для каждого SKILL.md используйте Content-Type: text/markdown.

Как мы проверяем Agent Skills?

Сканер делает GET-запрос на /.well-known/agent-skills/index.json и проверяет:

1. HTTP 200 — файл доступен
2. Валидный JSON — массив объектов
3. Обязательные поля — каждый skill содержит name, type, description, url, sha256
4. Доступность URL — первый skill из списка проверяется HEAD-запросом

pass — HTTP 200, валидный JSON, все обязательные поля присутствуют. fail — файл недоступен, структура нарушена или отсутствуют обязательные поля.