Agent Plugins 1.0.0: Общий формат упаковки для навыков и серверов MCP

Google, Microsoft, OpenAI, Cursor, Vercel и AWS поддержали проект Agent Plugins 1.0.0 — спецификацию, определяющую формат упаковки плагинов для ИИ-агентов. Она устанавливает структуру каталогов, формат файлов конфигурации и правила обнаружения двух типов компонентов: навыков и серверов MCP. Цель проекта проста: написать плагин один раз и использовать его в любом совместимом клиенте.

До сих пор существовало два основных способа придания кодинг-агенту новых возможностей. Навык представляет собой набор инструкций в формате Markdown, которые агент читает по мере необходимости. Сервер MCP — это отдельный процесс, соединяющий агента с внешними инструментами, API или базами данных. Контент обоих типов уже можно было переносить между инструментами, однако каждый инструмент имел свои правила организации каталогов, названий файлов конфигурации и местоположения файлов.

Версия 1.0.0 касается только внешней оболочки. Она не затрагивает внутреннюю структуру навыка и сам протокол MCP.

Почему это важно

Это имеет значение для трех групп:

• Авторы плагинов получают единую структуру каталогов, работающую во всех поддерживаемых клиентах. Больше не нужно хранить отдельные копии для Cursor, Copilot, Codex и других программ.
• Поставщики инструментов получают фиксированные места для файлов skills/ и mcp.json, поэтому им не приходится создавать собственную логику поиска или парсинга конфигураций. Поставщик всё равно может добавлять свои дополнения в каталог с именованным пространством без вмешательства в другие реализации.

Более широкая экосистема получает преимущества от трех дизайнерских решений: возможность нахождения пакетов через каталоги, отсутствие необходимости в дополнительной настройке помимо размещения файлов, а также ограничение последствий сбоев. Распространение становится проще, и авторы могут сосредоточиться на том, что создавать, а не на выборе инструментов.

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

Структура каталогов

Соответствующий плагин — это просто папка. Для примера под названием reports-plugin полная структура выглядит следующим образом:

reports-plugin/
├── plugin.json                  # Required: The only entry point for the plugin
├── skills/                      # Optional: Collection of skills
│   ├── summarize/               # One individual skill
│   │   ├── SKILL.md             #   Required: Skill definition file
│   │   ├── scripts/             #   Optional: Scripts used by the skill
│   │   │   └── analyze.sh
│   │   └── references/          #   Optional: Reference documentation for the skill
│   │       └── checklist.md
│   ├── deploy/                  # A second skill
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── rollback.sh
│   │   └── references/
│   │       └── runbook.md
│   └── code-review/             # A third skill
│       └── SKILL.md
├── mcp.json                     # Optional: MCP server configuration
├── com.cursor.tools/            # Optional: Cursor-specific extensions, other clients skip automatically
│   └── hooks/
│       └── hooks.json
├── LICENSE
└── CHANGELOG.md

Клиенты ищут информацию ровно в трех местах. Файл plugin.json указывает на папку как на допустимый плагин. Каждая подпапка первого уровня в каталоге skills/, содержащая файл SKILL.md, считается одним навыком. Файл mcp.json используется для настройки сервера MCP. Папки, названные в стиле обратного домена, например com.cursor.tools/, читаются только тем клиентом, к которому они принадлежат, а именно Cursor. Другие клиенты, включая ChatGPT и Codex, просто игнорируют их.

Манифест plugin.json

plugin.json — единственный обязательный файл, и его минимальная версия очень мала:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

Схема является замкнутой и включает десять разрешённых полей верхнего уровня: $schema, name, version, description, author, homepage, repository, license, keywords и extensions. Неизвестные поля фиксируются и игнорируются, при этом плагин всё равно загружается. С другой стороны, некорректное значение поля name приводит к проблемам: если оно отсутствует, имеет неверный тип или содержит недопустимые символы (большие буквы, двойные дефисы, пустая строка), весь плагин отклоняется.

Правила для поля name: длина от 1 до 64 символов, содержимое — только строчные буквы, цифры, дефисы и точки. Поле должно начинаться и заканчиваться буквой или цифрой, а подряд идущие два дефиса или две точки запрещены.

Как находятся компоненты

Обнаружение компонентов осуществляется исключительно на основе каталогов. Файл plugin.json не может перемещать компоненты в другие места или встраивать их конфигурацию непосредственно в код. Существуют только три вида местоположений:

• skills/: любой подкаталог первого уровня, содержащий файл SKILL.md, считается навыком. Глубже расположенные каталоги сканируются не будут.
• mcp.json: конфигурация сервера MCP.
• Каталоги расширений клиента: они называются в формате обратного домена, например com.example.client/, и игнорируются всеми остальными клиентами.

Отсутствие компонента не является ошибкой. Если каталог skills отсутствует или файл mcp.json не является обычным файлом, этот тип компонента будет отмечен как недействительный, в то время как остальные загрузятся как обычно.

Конфигурация MCP

mcp.json должен содержать два поля верхнего уровня: $schema и mcpServers. Значение поля $schema должно совпадать с тем, которое указано в plugin.json; в противном случае вся конфигурация MCP отклоняется.

Определены три способа передачи данных:

• stdio запускает локальный дочерний процесс. Параметр command представляет собой имя исполняемого файла, которое может быть получено из системного PATH или указано как путь относительно плагина, начинающийся с ./. Дополнительными полями являются args, env и cwd; по умолчанию значение cwd совпадает с корнем плагина.
• streamable-http — это текущий стандарт MCP Streamable HTTP.
• sse — это более старый способ передачи данных HTTP+SSE, предусмотренный спецификацией MCP от 2024-11-05, сохранённый для обратной совместимости.

Клиенты должны использовать как минимум stdio или streamable-http, причем их совместное использование предпочтительнее. sse является необязательным.

Переменные среды и постоянные данные

При запуске процесса stdio клиентом необходимо установить две переменные. PLUGIN_ROOT содержит абсолютный путь к корневой папке плагина. PLUGIN_DATA указывает на каталог с постоянными данными, предоставленный клиентом; этот каталог сохраняется после обновления плагина и удаляется при его деинсталляции.

Переменные ${PLUGIN_ROOT} и ${PLUGIN_DATA} могут встречаться в параметрах args, значениях env и пути cwd. Замена значений происходит за один проход в простом текстовом формате. Другие маркеры и расширение переменных в стиле шелла не поддерживаются.

Сбои остаются локальными

В спецификации на нескольких уровнях применяется правило «частичная неисправность не должна приводить к каскадному сбою»:

• Неудачная попытка запуска одного сервера MCP не влияет на другие серверы или навыки.
• Навык с повреждённой форматировкой игнорируется, в то время как остальные загружаются нормально.
• Запись MCP, использующая способ передачи данных, который не поддерживается клиентом, также игнорируется.
• Если файл mcp.json полностью недействителен, отключаются только компоненты MCP, но навыки продолжают загружаться.

Что не учтено в спецификации

В версии 1 отсутствуют информация о том, как устанавливаются плагины, контроль разрешений во время выполнения, аутентификация авторов, а также безопасное хранение секретов или ключей API. В тексте прямо говорится, что значения заголовков и параметров среды являются видимыми данными пакета и не представляют собой надежного способа сохранения конфиденциальной информации. Также отсутствует настройка OAuth и поле для хранения учетных данных, поэтому вопросы авторизации должны решаться каждым клиентом самостоятельно.

Кто включен, а кто нет

Поддержка запуска охватывает шесть клиентов: Kiro, VS Code, Cursor, GitHub Copilot, Codex и ChatGPT. В тот же день Google присоединился в качестве поддерживающей стороны, и его инструмент Agents CLI стал одним из первых продуктов, использующих этот формат. AWS также является одним из спонсоров.

Anthropic создала как формат навыков, так и MCP, а Claude Code с 2025 года использует практически идентичную структуру упаковки плагинов. Тем не менее Anthropic не входила в рабочую группу, и Claude Code отсутствует в первоначальном списке поддержки.

Пример работы «от начала до конца» с Google’s Agents CLI

Agents CLI является одним из первых пользователей этой технологии. После установки он предоставляет кодинговому агенту семь навыков, охватывающих шаблоны ADK, создание структуры проекта, оценку, развертывание и мониторинг.

Рассмотрим создание вспомогательного агента для работы с знаниями в формате RAG. Разработчик описывает цель простым языком, после чего агент действует самостоятельно:

1. Он создает структуру проекта на основе шаблона ADK agentic_rag, используя Vector Search в качестве хранилища данных.
2. Он замечает, что шаблон не поддерживает цитирование, переписывает инструкции агента с требованием использования встроенных цитат и меняет механизм поиска так, чтобы тот возвращал идентификаторы источников.
3. Он настраивает хранилище данных, загружает 12 справочных документов на Python в качестве корпуса и запускает тест на базовую работоспособность.

Перед развертыванием проводится оценка: 20 тестовых случаев в четырех группах — 6 на точность поиска, 5 на отказ при отсутствии контекста, 5 на многократное рассуждение и 4 на точность цитирования.

В ходе оценки был обнаружен один крайний случай, приводивший к галлюцинациям. По вопросам, не входящим в корпус, агент иногда отвечал на основе общих знаний вместо того, чтобы признать, что не знает ответа. Причиной было одно предложение в системном промпте, гласившее, что простые вопросы с известным ответом можно отвечать напрямую без использования инструментов. Удаление этого предложения полностью решило проблему.

Развертывание в Google Cloud занимает от двух до трех минут; функция Cloud Trace включена по умолчанию. После регистрации в Gemini Enterprise все сотрудники организации могут найти и использовать агента.