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 кожен у організації може знайти та використовувати агента.