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

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

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

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

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills":
}

А сам 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-агентам понятную, проверяемую инструкцию о том, как работать с вашим сайтом или сервисом.