Agent Skills Index: Как сайту стать видимым для AI-агентов

Мир поиска меняется. Классические поисковики индексируют страницы, AI-агенты — функциональность. Когда пользователь просит ChatGPT или Claude выполнить задачу на стороннем сайте, агенту нужен машиночитаемый способ понять, что он умеет делать на этом сайте и как этому научиться. Для этого существует открытый формат Agent Skills и механизм его обнаружения через /.well-known/agent-skills/.

Что такое Agent Skills?

Agent Skills — открытый формат, изначально предложенный Anthropic и с тех пор принятый рядом крупных платформ (Claude и Claude Code, OpenAI Codex CLI, Microsoft Agent Framework, Cursor, GitHub Copilot). Skill — это не вызываемый API-эндпоинт для бронирования или оплаты, а файл SKILL.md: YAML-заголовок с метаданными (обязательные поля name и description, опционально license, compatibility, metadata, allowed-tools) и Markdown-текст с пошаговой инструкцией, которую агент подгружает и использует, когда решает, что задача подходит под этот навык.

Skill может быть самодостаточным (один файл) или дополняться папками scripts/ (исполняемый код), references/ (документация) и assets/ (шаблоны, изображения) — агент подгружает их по мере необходимости, а не всё сразу.

Как агент находит навыки сайта

Отдельно от формата самого SKILL.md существует механизм обнаружения (discovery) — RFC, предложенный Cloudflare на основе RFC 8615 (well-known URI). Он определяет предсказуемое место, где агент может найти список навыков сайта:

Индекс обязателен по адресу /.well-known/agent-skills/index.json;

Каждый навык в индексе описан объектом с полями name, type (skill-md для одиночного файла или archive для навыка с ресурсами), description, url (куда идти за содержимым) и digest — SHA-256 хеш содержимого файла/архива в формате sha256:{hex};

Схема индекса версионируется и опубликована на schemas.agentskills.io.

Хеш digest нужен для проверки целостности: агент скачивает файл по url и сверяет его хеш с указанным в индексе. Если они не совпадают — содержимое повреждено или подменено, и агент обязан его отклонить.

Почему это важно именно для AI-агентов, а не для поисковиков?

Классические поисковые роботы (Googlebot, Yandex) индексируют HTML-страницы: текст, мета-теги, ссылки. Agent Skills решает другую задачу — даёт агенту предсказуемое, версионируемое и проверяемое место, где искать инструкции по работе с конкретным сайтом или сервисом, вместо того чтобы пытаться угадывать их, парся страницы.

Как выглядит index.json?

Минимальный пример корректного индекса:

{
"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
"skills": [
{
"name": "code-review",
"type": "skill-md",
"description": "Review code for bugs, security issues, and best practices.",
"url": "/.well-known/agent-skills/code-review/SKILL.md",
"digest": "sha256:c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4"
}
]
}

А сам SKILL.md, на который ссылается запись выше:

---
name: code-review
description: Review code for bugs, security issues, and best practices. Use when reviewing pull requests or diffs.
---

# Code review

1. Read the diff.
2. Check for common bug patterns...

Как правильно настроить и проверить

Шаг 1. Опишите навык. Создайте папку с файлом SKILL.md: имя навыка (только строчные латинские буквы, цифры и дефисы, до 64 символов, без дефиса в начале/конце) и описание (до 1024 символов, конкретное — что делает навык и когда его использовать).

Шаг 2. Опубликуйте по адресу. Разместите файл по пути /.well-known/agent-skills/{name}/SKILL.md и добавьте запись о нём в /.well-known/agent-skills/index.json с корректным SHA-256 digest содержимого файла.

Шаг 3. Настройте заголовки. Content-Type для index.json должен быть application/json. CORS-заголовок (Access-Control-Allow-Origin) рекомендован (SHOULD), если навыки предполагается вызывать из браузерных клиентов — но не обязателен для серверных агентов.

Шаг 4. Проверьте результат. Убедиться, что файл отдаётся, версия схемы актуальна и хеши совпадают, поможет бесплатный инструмент «Agent Skills Index» oWeb Solutions — он проверяет наличие файла по правильному well-known URI, CORS-заголовки, версию $schema и корректность SHA-256 digest для каждого навыка.

Типичные ошибки при настройке

Индекс есть, а самих файлов SKILL.md по указанным url — нет (404);

Устаревшая или неверная версия $schema;

Хеш digest не совпадает с реальным содержимым файла (посчитан от старой версии или неправильным алгоритмом);

Имя навыка не проходит валидацию (заглавные буквы, двойной дефис, дефис в начале строки).

Что дальше

Формат Agent Skills активно развивается и уже поддержан несколькими крупными AI-платформами. Рекомендуем: публиковать только реально полезные, проверенные навыки (не заготовки для галочки), периодически перепроверять индекс после любых изменений в навыках, и следить за обновлениями схемы на schemas.agentskills.io.

Внедрение — не формальность, а способ дать AI-агентам понятную, проверяемую инструкцию о том, как работать с вашим сайтом или сервисом.