Agent Skills Index: как AI-агенты узнают о возможностях вашего сайта

Вступление: контент для чтения против действий для выполнения

Когда мы говорим о сайте в классическом понимании, мы почти всегда имеем в виду совокупность страниц с текстом, изображениями и медиа. Пользователь приходит, читает, смотрит, переходит по ссылкам. Такой сайт — это, по сути, библиотека или витрина. Его задача — информировать, продавать через убеждение, формировать образ. Для поисковых систем и даже для простых ботов такой сайт описывается через карту сайта (sitemap.xml), где перечислены все URL, которые можно посетить и проиндексировать.

Но существует совершенно иной класс цифровых продуктов — сервисы. Это не просто «читать», это «делать». Интернет-магазин с корзиной, система бронирования столиков, сервис отслеживания посылок, личный кабинет с возможностью оплаты, API-платформа. У таких продуктов есть не только страницы, но и действия (actions) или, в терминологии современного ИИ, «навыки» (skills). Пользователь (или программа) не просто смотрит на информацию, а выполняет операцию: «проверить статус», «создать заказ», «забронировать», «рассчитать стоимость». И здесь возникает принципиальный вопрос: как автоматизированный агент, работающий на базе большой языковой модели (LLM), узнает, какие именно действия ему доступны на конкретном сайте?

Именно для решения этой задачи и появляется концепция Agent Skills Index. Это не просто техническая спекуляция, а попытка создать мост между «сайтом как контентом» и «сайтом как функцией». В этой статье мы разберем, что это такое, как это работает, почему это еще не стандарт, но уже становится важной практикой для тех, кто хочет, чтобы их сервис был доступен AI-агентам.

Аналогия с sitemap.xml, но для действий, а не страниц

Чтобы понять суть, проще всего провести прямую параллель с протоколом Sitemap Protocol. Когда вы создаете sitemap.xml, вы сообщаете поисковому роботу Google или Яндекса: «Вот список всех значимых URL на моем домене. Приходи и индексируй их». Робот читает файл, понимает структуру, приоритеты, даты обновления и отправляется собирать контент. Без этого файла робот все равно найдет страницы через ссылки, но процесс будет медленнее и менее предсказуемым.

Agent Skills Index работает по той же логике, но с одним важным отличием: он перечисляет не страницы для чтения, а действия для вызова. Если sitemap.xml отвечает на вопрос «где лежит информация?», то Agent Skills Index отвечает на вопрос «что я могу здесь сделать?» или «какие операции мне доступны?».

Представьте, что вы — разработчик AI-платформы для путешествий. Ваш агент находит сайт авиакомпании. Обычный поисковый робот увидит страницы с расписанием, правилами провоза багажа, информацией о статусе рейса. Но агенту, который должен помочь пользователю купить билет или зарегистрироваться на рейс, этого недостаточно. Ему нужно знать: существует ли метод «поиск рейса по дате и направлению», принимает ли сайт данные для бронирования, есть ли функция «отмена брони». Эти знания агенту может дать только машиночитаемый файл, который явно перечисляет доступные функции и параметры для их вызова.

Таким образом, Agent Skills Index — это декларативное описание «поверхности» API или интерактивных элементов сайта, которое выставляется в открытый доступ для чтения AI-агентами до того, как агент решит, стоит ли вообще пытаться взаимодействовать с этим ресурсом и как именно это делать.

Разбор структуры индекса: JSON, версия схемы и хеши

На сегодняшний день не существует единого ратифицированного стандарта для Agent Skills Index (об этом мы подробно поговорим ниже). Однако сообщество разработчиков и интеграторов постепенно приходит к консенсусу относительно базовой структуры. Наиболее распространенным форматом является JSON-документ, размещаемый по одному из предсказуемых адресов (например, /.well-known/agent-skills.json или /skills.json).

Вот как выглядит типичная (но не единственно возможная) структура такого файла:

{
  "schema_version": "1.0",
  "service": "example-delivery-service",
  "description": "Сервис доставки еды. Позволяет искать рестораны, оформлять заказ и отслеживать курьера.",
  "skills": [
    {
      "id": "search_restaurants",
      "name": "Поиск ресторанов",
      "description": "Возвращает список ресторанов, работающих в данный момент, с фильтрацией по кухне и времени доставки.",
      "input_schema": {
        "type": "object",
        "properties": {
          "cuisine": { "type": "string", "description": "Тип кухни" },
          "max_delivery_time": { "type": "integer", "description": "Максимальное время доставки в минутах" }
        }
      },
      "endpoint": "https://api.example.com/v1/restaurants/search",
      "method": "GET",
      "sha256_hash": "9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f1a2b"
    },
    {
      "id": "place_order",
      "name": "Оформление заказа",
      "description": "Создает новый заказ в выбранном ресторане. Требуется авторизация.",
      "input_schema": {
        "type": "object",
        "properties": {
          "restaurant_id": { "type": "string" },
          "items": { "type": "array", "items": { "type": "object" } }
        },
        "required": ["restaurant_id", "items"]
      },
      "endpoint": "https://api.example.com/v1/orders",
      "method": "POST",
      "auth_required": true,
      "sha256_hash": "2f4a1b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1"
    }
  ]
}

Рассмотрим ключевые элементы этого индекса.

schema_version (версия схемы) — это критически важное поле. Поскольку стандарт находится в стадии формирования, структура файла может меняться. Агент, который читает индекс, должен сначала проверить версию, чтобы понять, как интерпретировать остальные поля. Если разработчик сайта изменит структуру с 1.0 на 2.0, старый агент не должен «ломаться» или пытаться парсить файл по старой логике. Он либо должен уметь обрабатывать новую версию, либо честно сообщить, что не поддерживает этот формат. Это аналог HTTP-заголовка Content-Type, который сообщает браузеру, как читать тело ответа.

skills — это массив объектов. Каждый объект описывает одно действие. Обязательными здесь являются поля id (уникальный идентификатор), name (человекочитаемое название) и description (подробное описание, которое агент использует для понимания семантики действия). Именно описание играет решающую роль: LLM-агент не выполняет код вслепую, он «читает» описание и решает, подходит ли этот навык для текущей задачи пользователя.

Далее идет input_schema — описание входных параметров. Мы используем JSON Schema, потому что это де-факто стандарт для описания структурированных данных. Агент читает эту схему и генерирует корректный JSON-запрос для вызова навыка. Без этого поля агенту пришлось бы угадывать параметры, что привело бы к ошибкам.

Поля endpoint и method указывают, куда и каким HTTP-методом отправлять запрос. Опционально может быть поле auth_required (требуется ли авторизация), а также sha256_hash (о нем мы поговорим отдельно).

SHA256-хеши отдельных навыков — это опциональный, но очень дальновидный механизм безопасности. Когда агент читает индекс, он видит описание навыка и хеш этого описания. Предположим, индекс говорит: «Навык place_order имеет хеш 2f4a...». Агент сохраняет это значение. Прежде чем вызвать навык, агент (или его среда выполнения) может повторно запросить актуальное описание с сервера, вычислить его хеш и сравнить с тем, что было в индексе. Если хеши совпадают — описание не изменилось с момента чтения индекса. Если не совпадают — это сигнал тревоги: возможно, описание было подменено атакующим (например, при атаке Man-in-the-Middle или компрометации файла). Это защита от атак, когда злоумышленник модифицирует описание навыка, чтобы агент выполнил нежелательное действие (например, отправил деньги на счет злоумышленника, думая, что оплачивает заказ).

Зачем нужен CORS-заголовок и что будет без него

Здесь мы подходим к одному из самых важных технических аспектов, который часто упускают из виду. Agent Skills Index может читаться двумя типами агентов:

• Серверные боты (server-side) — запускаются на мощностях облачного провайдера, в дата-центре. У них нет ограничений браузера.
• Клиентские агенты (client-side) — работают внутри браузера пользователя. Например, это может быть браузерное расширение или веб-приложение, которое отправляет запросы от имени пользователя.

Проблема возникает именно с клиентскими агентами. Веб-браузеры реализуют политику Same-Origin Policy (SOP). Эта политика запрещает JavaScript-коду, загруженному с одного домена (например, agent-platform.com), делать запросы на другой домен (your-service.ru) без явного разрешения со стороны ресурса. Это фундаментальный механизм безопасности, предотвращающий кражу данных и подделку запросов.

Представьте, что пользователь зашел на сайт вашего GEO-агентства, и там встроен AI-ассистент. Ассистент хочет проверить, есть ли у сайта some-shop.com Agent Skills Index. Браузер отправляет fetch-запрос на https://some-shop.com/.well-known/agent-skills.json. Если сервер some-shop.com не вернет в ответе HTTP-заголовок Access-Control-Allow-Origin (например, со значением * или конкретным доменом вашего агента), браузер заблокирует чтение ответа. JavaScript получит ошибку CORS. Агент не сможет прочитать ни одного байта индекса, даже если файл технически существует и доступен.

Что будет без CORS-заголовка? Агент, работающий в браузере, будет полностью слеп. Он не сможет узнать о навыках сайта. Он либо просто скажет пользователю, что сайт не поддерживает автоматизацию, либо попытается «спарсить» HTML-страницу и угадать действия, что крайне ненадежно. В итоге, если вы хотите, чтобы ваш сайт могли использовать клиентские AI-агенты, вы обязаны настроить CORS-заголовки на сервере, отдающем файл индекса. Это требование не является частью «стандарта» (которого нет), но это жесткое требование веб-платформы.

Важно подчеркнуть: для серверных ботов CORS не нужен, потому что они не работают в браузере и не подчиняются SOP. Но если вы не знаете заранее, кто будет читать ваш индекс (браузер или сервер), безопаснее всего настроить Access-Control-Allow-Origin: * (или ограничить список доменов, которым вы доверяете).

Зачем нужны SHA256-хеши и как это защищает от подмены

Мы уже кратко упомянули хеши, но давайте углубимся в сценарий атаки, который они предотвращают. Допустим, ваш сервис принимает заказы. Агент читает индекс и видит навык place_order с хешем 2f4a.... Агент доверяет этому описанию. Но что, если злоумышленник перехватил трафик (или внедрил вредоносный скрипт на CDN) и модифицировал сам файл индекса? Он может изменить описание навыка так, чтобы параметр amount (сумма) стал называться recipient_address (адрес получателя), а описание стало бы убеждать агента, что это поле для ввода почтового индекса.

Агент, слепо доверяющий индексу, сгенерирует запрос, который на самом деле отправит деньги злоумышленнику. Хеширование решает эту проблему частично, но эффективно.

Как это работает на практике:

1. Агент читает индекс. Он видит навык place_order и его хеш H1.
2. Агент запрашивает с сервера актуальное «слепок» описания навыка (например, через отдельный эндпоинт или через повторное чтение индекса, но по защищенному каналу).
3. Агент вычисляет SHA256 от полученного описания (от канонической JSON-строки или от байтового представления).
4. Если вычисленный хеш H2 не равен H1 из индекса, агент останавливает выполнение. Он понимает: либо индекс был подменен, либо описание навыка изменилось после чтения индекса. В любом случае, доверять текущему состоянию нельзя.

Важно понимать ограничения: если атакующий может подменить и индекс, и сам навык (оба файла), и у него есть доступ к серверу, то хеши не спасут. Но в большинстве реалистичных сценариев (атака на кеш CDN, перехват одного запроса) хеширование дает агенту возможность обнаружить несоответствие. Это механизм сверки целостности, а не шифрование. Он не скрывает данные, он лишь подтверждает, что данные не менялись между чтением индекса и фактическим вызовом.

Честно: почему это ещё не стандарт и что это значит на практике

Нам важно быть максимально прозрачными: на момент написания этой статьи (а это развивающаяся область) не существует официального документа IETF, W3C или другой авторитетной организации, который бы назывался «Agent Skills Index Specification». Нет единого реестра, нет обязательных требований. Это не стандарт вроде HTML или HTTP.

То, что мы описываем — это конвенция, которая стихийно формируется в экосистеме разработчиков AI-агентов, интеграторов и владельцев сервисов. Есть похожие концепции, например, MCP Server Card (о котором мы писали в отдельной статье), но это другая, самостоятельная идея. MCP (Model Context Protocol) — это протокол для подключения инструментов к агенту, а Server Card — это способ описания самого MCP-сервера. Agent Skills Index — это более широкая и одновременно более простая концепция: он не требует создания полноценного MCP-сервера, а просто предоставляет JSON-список возможностей, которые могут быть реализованы через обычный REST API или даже через HTML-формы, которые агент может «заполнить».

Что означает отсутствие стандарта на практике?

Плюс: Нет бюрократии. Вы можете прямо сейчас создать файл skills.json в корне сайта и структурировать его так, как удобно вам. Агенты, которые ищут этот файл, будут проверять несколько распространенных путей. Мы, в нашем инструменте «Проверка Agent Skills Index», как раз ищем файлы по путям /.well-known/agent-skills.json, /.well-known/skills.json и /skills.json.

Минус: Нет гарантий совместимости. Разные агенты могут ожидать разные структуры. Ваш файл может быть идеально логичным, но конкретный агент его не поймет, если ожидает другие имена полей. Отсутствие стандарта также означает, что инструменты для валидации и тестирования только зарождаются. Скорее всего, в ближайшие годы появятся более формальные спецификации, возможно, на базе обобщения практик, которые мы видим сейчас.

Мы рекомендуем относиться к Agent Skills Index как к «экспериментальной фиче» (feature flag) в хорошем смысле слова. Это возможность выделиться и подготовиться к будущему, но не стоит ожидать, что все агенты мира начнут использовать ваш индекс уже завтра. Это скорее стратегическая инвестиция в машиночитаемость вашего сервиса.

Кому это нужно уже сейчас, а кому рано

Давайте четко разделим аудиторию.

Кому это нужно уже сейчас:

• Сервисам с реальными действиями поверх данных (поиск, бронирование, оформление заказа, проверка статуса, расчет стоимости доставки). Если ваш сайт позволяет пользователю что-то сделать, а не только прочитать, вам стоит задуматься о создании индекса.
• Платформам, предоставляющим публичные API. Если у вас есть API, вы можете описать его ключевые методы как навыки, чтобы агенты могли вызывать их без необходимости читать длинную документацию.
• Интернет-магазинам с большим каталогом и сложной логикой заказа. Агент, который может «поискать товар по характеристикам» и «оформить заказ», станет вашим виртуальным продавцом.
• Сайтам, которые хотят интегрироваться с AI-ассистентами (например, голосовыми помощниками или чат-ботами) без написания кастомных интеграций.

Кому рано:

• Обычным контентным сайтам (блогам, новостным порталам, корпоративным лендингам), где нет интерактивных действий, кроме отправки контактной формы. Для таких сайтов sitemap.xml и разметка Schema.org (Article, FAQPage) гораздо важнее. Агенты прекрасно справляются с чтением контента без Skills Index.
• Сайтам, которые не имеют технической возможности настроить CORS-заголовки или разместить файл в well-known директории. Если сайт на конструкторе, который не дает доступа к серверным настройкам, внедрение будет затруднено.
• Проектам, которые не готовы поддерживать актуальность индекса. Если вы описали навык «оформление заказа», но потом изменили API и забыли обновить индекс, агенты будут вызывать несуществующие эндпоинты и получать ошибки. Это хуже, чем отсутствие индекса, потому что подрывает доверие.

Наш инструмент проверки как раз помогает определить, находитесь ли вы в первой группе. Если вы запустите проверку и увидите, что файл не найден или массив skills пуст, это не приговор. Это сигнал к размышлению: а есть ли у вашего сайта «навыки», которые стоит описать?

Как проверить у себя

Процесс проверки прост и не требует специальных знаний. Мы разработали инструмент «Проверка Agent Skills Index», чтобы вы могли быстро оценить текущее состояние вашего сайта.

Алгоритм работы инструмента следующий:

1. Вы вводите URL вашего сайта (например, example.com).
2. Инструмент последовательно проверяет несколько распространенных путей размещения индекса:
   • /.well-known/agent-skills.json
   • /.well-known/skills.json
   • /skills.json
3. Для каждого найденного файла инструмент проверяет:
   • Является ли ответ валидным JSON.
   • Содержит ли объект поле skills или index.
   • Является ли это поле массивом и не пустой ли он (наличие хотя бы одного навыка).
4. Отдельно проверяется наличие HTTP-заголовка Access-Control-Allow-Origin в ответе. Это критично для клиентских агентов, как мы обсуждали выше.

Если инструмент не находит файл, это не означает, что все плохо. Это означает, что ваш сайт пока не готов к взаимодействию с AI-агентами через этот механизм. Если файл найден, но массив пуст, это говорит о том, что вы разместили заглушку, но не описали ни одного навыка. Инструмент также покажет, есть ли проблемы с CORS — это одна из самых частых ошибок при внедрении.

Рекомендуем также проверить, как ваш сайт выглядит для MCP-клиентов. Если вы планируете более глубокую интеграцию, изучите нашу статью про MCP Server Card — это смежная, но более сложная концепция для организации постоянного канала связи между агентом и вашим сервисом.

FAQ

1. Чем Agent Skills Index отличается от MCP Server Card?

Это два разных подхода к одной проблеме — как познакомить агента с возможностями сервиса. MCP Server Card — это метаданные о MCP-сервере, который реализует протокол Model Context Protocol. MCP — это полноценный протокол с JSON-RPC, сессиями, авторизацией и инструментами. Server Card описывает, как подключиться к этому серверу (URL, транспорт, возможности). Agent Skills Index — это более легковесная и независимая концепция. Он не требует запуска отдельного MCP-сервера. Это просто JSON-файл, который описывает ваши REST-эндпоинты или даже логику HTML-форм. Если MCP можно сравнить с полноценным SDK для интеграции, то Skills Index — это скорее «визитная карточка» или «меню» вашего сайта. Агент может прочитать это меню и решить, как действовать дальше, используя стандартные HTTP-запросы.

2. Какой путь размещения файла самый правильный?

Единого стандарта нет, но наиболее распространенным и «экологичным» считается путь /.well-known/agent-skills.json. Использование директории .well-known — это общепринятая практика для размещения метаданных (например, security.txt, assetlinks.json). Однако многие агенты также проверяют /skills.json в корне. Мы рекомендуем разместить файл по одному из этих адресов и убедиться, что он доступен по HTTPS. Вы можете разместить его по всем трем путям, чтобы максимизировать совместимость, но тогда не забудьте синхронизировать содержимое.

3. Может ли Agent Skills Index заменить sitemap.xml?

Нет. Это разные инструменты для разных задач. Sitemap.xml говорит поисковому роботу о контенте для индексации. Agent Skills Index говорит AI-агенту о действиях для выполнения. Контентный сайт может вообще не иметь Skills Index, но обязан иметь sitemap.xml. Сервис с API может иметь и то, и другое. Это не взаимозаменяемые вещи, а дополняющие друг друга аспекты машиночитаемости.

4. Безопасно ли открывать информацию о своих API в индексе?

Индекс описывает только сигнатуру вызова (параметры и метод), но не раскрывает секреты, ключи доступа или внутреннюю логику. Он сообщает агенту: «есть такой эндпоинт, он принимает такие-то параметры». Это равносильно публикации документации к API. Риск возникает только в том случае, если сам эндпоинт не защищен должным образом. Если ваш API требует авторизации (поле auth_required: true), агент должен будет ее пройти. Индекс не отключает систему безопасности, он лишь облегчает навигацию. Однако, если у вас есть уязвимые эндпоинты, которые вы не хотите афишировать, не включайте их в индекс.

5. Что делать, если я изменил API, но забыл обновить индекс?

Это плохая практика, которая приводит к ошибкам у агентов. Агент прочитает устаревшее описание, вызовет несуществующий метод или передаст неправильные параметры. В итоге он получит ошибку 404 или 400. Чтобы избежать этого, введите в процесс разработки правило: изменение любого эндпоинта, который описан в индексе, должно сопровождаться обновлением индекса и пересчетом SHA256-хеша (если вы его используете). Некоторые компании автоматизируют этот процесс, генерируя индекс на основе спецификации OpenAPI (Swagger). Это правильный подход.

6. Как часто агенты проверяют этот индекс?

Однозначного ответа нет. Некоторые агенты кешируют индекс на длительное время (до 24 часов), другие проверяют его при каждом новом сеансе взаимодействия с сайтом. Поэтому важно, чтобы файл всегда был доступен и возвращал корректные CORS-заголовки. Если агент один раз получил ошибку CORS, он может запомнить сайт как «неподдерживающий интеграцию» и не возвращаться к нему. Если вы добавили индекс после того, как агент уже посещал сайт, ему потребуется время, чтобы обнаружить изменения. Это еще одна причина, почему данная практика только формируется: поведение агентов еще не устоялось, и они могут по-разному обрабатывать кеширование.

В заключение подчеркнем: Agent Skills Index — это не волшебная таблетка, а скорее «приглашение к диалогу» для AI-агентов. Вы открываете дверь и показываете, что у вас есть функции, которые можно вызывать. Сделайте это правильно, настройте CORS, поддерживайте файл в актуальном состоянии, и вы станете частью формирующейся экосистемы, где сайты — это не просто страницы, а живые сервисы, готовые к автоматизации.