Что такое Agent Plugins 1.0.0: plugin.json, MCP, Agent Skills и раскладка JSON (2026)

Перед чтением

Файл	Что требует спецификация	Чего она не делает
plugin.json	Единственный манифест, в корне. Обязательны $schema и name. Список полей закрыт	Нельзя встроить MCP и нельзя перенести путь компонента
skills/	Только SKILL.md в непосредственном дочернем каталоге. Формат принадлежит спецификации Agent Skills	Без рекурсии. Отсутствие каталога — не ошибка
mcp.json	На верхнем уровне только $schema и mcpServers. У каждого сервера есть type	Инструмент не выполняет. В 1.0.0 нет переносимых полей учётных данных
Каталог расширения	Папка обратного домена, например com.example.client/. extensions использует те же пространства	Другие клиенты должны уметь её игнорировать

Факты из спецификации Agent Plugins 1.0.0, заметки Vercel и Google Developers Blog, все от 6 августа 2026. Заказ A-1042 и orders.example.com вымышлены.

Он складывает навыки и серверы MCP в один каталог, который можно перенести

Agent Plugins 1.0.0 стал публичным 6 августа 2026 года. Основные сопровождающие тогда были из Amazon, Cursor, Microsoft, OpenAI и Vercel. В тот же день Google Developers Blog написал, что Google входит в эту группу в лице Kevin Hou и начинает поддержку в своих продуктах. Это не частный формат, который Google опубликовал в одиночку. Спецификация задаёт два переносимых типа компонентов: Agent Skills и серверы MCP. Установка, распространение, политика и интерфейс остаются у клиента. Клиент проверяет корневой plugin.json до поиска компонентов. При загрузке плагина он не должен скачивать Schema по сети.

• Манифест: $schema обязан быть https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. name обязателен.
• Навыки: skills/<имя>/SKILL.md. Только непосредственные дети. Без рекурсии.
• MCP: корневой mcp.json. Каждая запись указывает stdio, streamable-http или необязательный старый sse.

Как MCP идёт по проводу: как агент для кода вызывает MCP. Чем схема инструмента MCP отличается от function calling: схема инструмента MCP и function calling. Этот текст их не переписывает. Он говорит только, чем владеют два JSON-файла в каталоге плагина.

Список полей plugin.json закрыт

Разрешены только $schema, name, version, description, author, homepage, repository, license, keywords и extensions. Первые два обязательны. Имя — от 1 до 64 символов, только строчные буквы, цифры, дефисы и точки, начинается и кончается буквой или цифрой и не содержит -- или ... Для version рекомендуют семантические версии, но строка не в SemVer сама по себе не причина отказа. В author могут быть только name, email и url. Вымышленный плагин заказа:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "orders-plugin",
  "version": "1.0.0",
  "description": "Look up fictional order A-1042. No refunds.",
  "license": "Apache-2.0",
  "keywords": ["orders"]
}

Неизвестное поле верхнего уровня нужно сообщить и проигнорировать. Загрузка продолжается, если остальное верно. Отсутствие обязательного поля, неверный тип или незаконное имя отклоняют весь пакет. Компоненты не ищутся и не выполняются. Данные клиента кладут в extensions, ключ — обратный домен, каждое значение — объект. Другой файл не может переопределить основные поля корневого манифеста.

Навыки и MCP нельзя писать в манифест

Спецификация фиксирует места. Каждый непосредственный потомок skills/, в котором есть обычный файл с именем ровно SKILL.md, — это один навык. Преамбула и каталоги scripts/, references/, assets/ принадлежат спецификации Agent Skills. Эта спецификация говорит только, как навык находят, а не как клиент показывает его модели. MCP нельзя встроить в plugin.json и нельзя перенести на другой путь. На верхнем уровне mcp.json только $schema и mcpServers. Пустой mcpServers допустим. Версии двух $schema должны совпадать. Идентификатор MCP для 1.0.0 — https://agent-plugins.org/schemas/1.0.0/mcp.schema.json. Для stdio обязательны type и command. args, env и cwd необязательны. Путь с ./ относителен корню плагина. ../ не должен выходить за этот корень. Клиент раскрывает PLUGIN_ROOT и PLUGIN_DATA:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "orders": {
      "type": "stdio",
      "command": "./bin/orders",
      "args": ["--data", "${PLUGIN_DATA}/orders"],
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

Удалённый сервер использует streamable-http и требует url. sse — устаревший необязательный транспорт. Спецификация не задаёт запасной вариант, если соединение не удалось. Соответствующий клиент поддерживает хотя бы один из stdio и streamable-http и лучше оба. В версии 1.0.0 нет переносимых полей OAuth или ссылок на учётные данные. Аутентификация остаётся у клиента. Правила путей касаются файлов пакета. Они не сажают подпроцесс в песочницу. Аргументам инструмента всё ещё нужны свои ворота Schema: зачем ИИ нужен JSON Schema.

Сломанная часть останавливается на своей границе

Спецификация разделяет сбои. Не читайте один плохой JSON как мёртвый пакет:

Клиент игнорирует типы компонентов, которые не поддерживает. Каталог обратного домена вроде com.example.client/ принадлежит одному клиенту. Остальные должны уметь его пропустить. Неизвестные пространства в extensions игнорируются так же. Как песочница останавливает уже отправленный tools/call, — другой слой: OpenShell и Sentry.

Шесть проверок перед выпуском плагина

Не начинайте с того, чтобы вставить URL MCP-сервера в plugin.json:

1. Сначала напишите корневой plugin.json. Только ключи из закрытого списка. Имя вроде orders-plugin остаётся строчным.
2. Каждый навык кладите в непосредственного потомка. skills/lookup-order/SKILL.md. Более глубокий каталог не найдут.
3. MCP пишите только в mcp.json. У каждой записи есть type. Локальный сервер использует stdio и ./bin/orders. Без ../.
4. Оба $schema направьте на 1.0.0. При несовпадении навыки ещё могут загрузиться. MCP — нет.
5. Учётные данные оставьте клиенту. В mcp.json версии 1.0.0 нет переносимого поля секрета. Не коммитьте токен в env или headers.
6. Аргументам инструмента дайте свою Schema. Манифест только указывает сервер. Хост всё равно проверяет A-1042 перед поиском.

Плагин без skills/ и без mcp.json может быть допустимым. Обязателен только plugin.json.

Разложите оба JSON перед слиянием

Неудачная загрузка — это либо отклонённый пакет, либо пропущенный MCP-сервер. Разделите это, прежде чем править подсказку.

• форматировать plugin.json и mcp.json, затем проверка Schema: нет ли лишнего ключа верхнего уровня и не отсутствует ли $schema.
• Через извлечение JSONPath достаньте $.name, $.mcpServers.orders.type и $.mcpServers.orders.command.
• JSON Diff манифест с предыдущей ревизией. Проверьте, что путь не выходит за корень плагина.
• Убедитесь, что skills/lookup-order/SKILL.md — обычный файл в непосредственном потомке, а не более глубокий файл.
• Токены в конфигурации сначала уберите, на своей машине. mcp.json с секретом не вставляйте в публичный форматтер. JSONSort работает в браузере.

Если оба JSON собираются заново по закрытому списку полей и каталоги стоят на фиксированных местах, плагин соответствует 1.0.0. Выполнит ли клиент поиск, манифест не решает.

Частые ошибки

• Записать это как частный формат плагинов Google. Тексты 6 августа 2026 описывают спецификацию между поставщиками. Google в тот день присоединился как основной сопровождающий.
• Положить mcpServers внутрь plugin.json. Спецификация запрещает встроенную конфигурацию и перенос пути. Клиенты читают только корневой mcp.json.
• Угадывать транспорт по форме объекта. Каждому серверу нужен type. Нет правила, что значение в форме URL означает HTTP.
• Положить ключ API в mcp.json. В версии 1.0.0 нет переносимого поля учётных данных. Аутентификация остаётся у клиента. Пример использует вымышленный заказ.
• Выбросить все навыки, потому что один сервер не запустился. Сбой одного сервера отключает только эту запись. Неверный mcp.json верхнего уровня отключает MCP. Навыки продолжают загружаться.
• Этим текстом переписать сравнение MCP и function calling. Здесь только то, как плагин кладёт уже существующую конфигурацию MCP в фиксированный файл.

FAQ

Каталог только с plugin.json — допустимый плагин?

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

Что будет, если два значения $schema не совпадут?

Конфигурация MCP недействительна. Навыки и другие типы компонентов остаются действительными. В 1.0.0 оба файла используют идентификатор 1.0.0 из спецификации, и версии должны совпадать.

Можно ли положить SKILL.md в skills/orders/extra/?

Его не найдут. Клиент смотрит только непосредственных потомков skills/ и не идёт глубже. Файл должен быть обычным файлом вроде skills/lookup-order/SKILL.md.

Нужно ли объявлять и stdio, и streamable-http?

Нет. Один сервер использует один type. stdio нужен command. streamable-http нужен url. sse устарел, клиент может его не поддерживать. Спецификация не переключает транспорт, если соединение не удалось.

Этот JSON сам ищет заказ?

Нет. plugin.json называет плагин. mcp.json говорит клиенту, где сервер. tools/call выполняет хост. Аргумент вроде A-1042 нуждается в своей проверке Schema. В манифесте нет переносимого поля секрета.

Вывод

Agent Plugins 1.0.0 складывает Agent Skills и серверы MCP в один корневой каталог, который можно перенести. plugin.json фиксирует версию спецификации и имя. Места компонентов в манифесте не меняются.

Проверьте, что orders-plugin лежит в plugin.json, ./bin/orders — в mcp.json, а SKILL.md — в непосредственном потомке. Когда эти три места фиксированы, клиенту не нужно гадать, куда вы спрятали конфигурацию.

Дальше по теме

• Как агент для кода вызывает MCP Форма tools/call на проводе. Этот текст её не переписывает
• Схема инструмента MCP и function calling Сравнение протоколов, а не каталог плагина
• Зачем ИИ нужен JSON Schema После того как сервер найден, аргументам всё ещё нужны ворота
• OpenShell и Sentry Как песочница останавливает уже отправленный tools/call
• Локальные инструменты JSONSort Формат, проверка, Diff, Schema
• Все статьи Другие заметки о JSON и разработке ИИ

История: 2026-10-12 Первая публикация