# agent-skills

## Что такое Agent Skills?

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

```json
{
  "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`:

```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](/glossary/a2a-agent-card)** — оркестраторы, поддерживающие A2A, читают skills из `/.well-known/agent.json`.

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

```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** — файл недоступен, структура нарушена или отсутствуют обязательные поля.

[← Все термины глоссария](/glossary)