Как Agent Plugins дают AI-агенту новые умения: манифест, Skills, MCP и JSON после установки

Пять прыжков, не «модель научилась»

«Агент сам получил умение» звучит так, будто модель выучила навык. В инженерии это пять прыжков, ни один не пропустить. Первый: клиент ставит каталог корнем плагина; разрешённый путь за пределы корня отвергается, в том числе симлинк наружу. Второй: прочитать plugin.json, пройти закрытую схему, взять name и версию спецификации. Падение здесь — отказ всего пакета, прыжки три–пять не идут. Третий: если есть skills/, смотреть только прямых детей с обычным файлом ровно SKILL.md и класть в контекст name и description. Четвёртый: если есть mcp.json, соединяться по каждому type, затем tools/list после рукопожатия. Пятый: модель совпала с описанием или именем инструмента — тогда читает тело Skill или шлёт tools/call.

Спецификация нарочно не описывает кнопку установки. Google Developers Blog пишет открыто: установка, права, песочница и UX подтверждения — обязанность каждого клиента. У Agents CLI, Cursor и Claude Code могут быть три разных диалога. Переносится каталог и два закрытых JSON. На ревью спрашивают не «куда кликает пользователь», а «какие объекты теперь в памяти». Нет манифеста — нет следующих прыжков. Манифест прошёл, но $schema у mcp.json не совпал с plugin.json: MCP гасится, навыки остаются. Один SKILL.md не по Agent Skills — пропускаем только его.

Горизонтальное делегирование вне этого конвейера. Как найти агент счетов другой команды — это Agent Card, см. текст про A2A. Сегодня только о том, как этот кодирующий агент наращивает набор навыков и инструментов. Назовите «новое умение» результатом открытия и смотрите JSON каждого прыжка.

Сначала манифест: plugin.json — контракт личности

Клиент ОБЯЗАН прочитать корневой plugin.json до открытия компонентов. Файл нельзя переименовать, навыки и MCP нельзя встроить в манифест. Схема закрытая: только $schema, name, version, description, author, homepage, repository, license, keywords, extensions. Лишние ключи верхнего уровня ОБЯЗАН сообщить и проигнорировать — это не причина отвергнуть плагин. Смертельно: нет обязательного поля, не тот тип, незаконный name — пакет целиком, компонентов ноль. Для 1.0.0 $schema ОБЯЗАН быть https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. Клиент выбирает по нему локальные правила и НЕ ДОЛЖЕН качать схему во время загрузки.

name — идентификатор, не витринное имя. Длина 1–64; только строчные, цифры, дефис и точка; первый и последний символы буквенно-цифровые; без -- и ... My-Plugin и -start валят весь пакет. SemVer для version рекомендуется, но «не похоже на SemVer» — не отказ. В объекте author только name / email / url. Частное клиента — в extensions.com.example.client или в каталоге обратного домена в корне. Пятый ключ верхнего уровня под хуки не изобретать. Хуки в корне plugin.json спецификация велит игнорировать: ваша IDE вдруг прочитает, следующая — нет.

Ниже полный манифест в репозиторий: больше минимума из двух полей, с метаданными для людей. Сначала parse и официальная схема, потом спор про кнопку установки. keywords помогают каталогу. description помогает человеку решить, ставить ли. Модели выбрать инструмент она не помогает. Навыки выбирают по description в SKILL.md, инструменты — по tools/list. Инструкция к инструменту в манифесте оставляет поверхность открытия пустой.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "invoice-ops",
  "version": "1.2.0",
  "description": "Invoice query MCP plus the weekly-summary skill, shipped as one directory",
  "author": {
    "name": "Finance Platform",
    "url": "https://docs.example.com/invoice-ops"
  },
  "homepage": "https://docs.example.com/invoice-ops",
  "repository": "https://github.com/example/invoice-ops",
  "license": "MIT",
  "keywords": ["invoices", "weekly-summary", "mcp"]
}

После установки: снимок способностей у клиента

Спецификация не требует файла «установленные способности». Ревью всё равно должно видеть, что лежит в памяти. Сложите пять прыжков в один JSON-снимок: личность плагина, найденные навыки (только метаданные), состояние MCP, контракты инструментов из tools/list. Этот снимок не экземпляр plugin.schema.json — не проверяйте его схемой упаковки. Это фикстура CI: число навыков, имена инструментов, обязательные поля inputSchema. Установка прошла, снимок не совпал — сломалось открытие или рукопожатие. Модель ничего «не недоучила».

«Получено автоматически» видно в этом объекте. skills[].loaded — metadata, не body: около ста токенов на старте, тело по требованию. tools[] приходит из tools/list после рукопожатия, не из рукописного списка в plugin.json. mcpServers[].status — рантайм, не контракт упаковки. Пустой tools при connected значит: рукопожатие прошло, сервер ничего не отдал — смотрите сервер, не манифест. Наоборот, валидный манифест и ноль навыков в снимке: чаще всего SKILL.md спрятан на уровень глубже.

После Google Cloud Developer Plugin сторона клиента того же вида: личность ящика, метаданные навыка-ограничителя gcloud, список инструментов Developer Knowledge MCP. Пользователи говорят «агент теперь ищет Cloud-документацию». В данных tools вырос на несколько записей. Diff снимка и закоммиченных plugin.json / mcp.json сразу ловит того, кто записал рантайм обратно в упаковку. Это drift, не поле спецификации.

{
  "plugin": {
    "name": "invoice-ops",
    "version": "1.2.0",
    "spec": "1.0.0"
  },
  "skills": [
    {
      "name": "write-weekly-summary",
      "description": "Turn invoice query results into the weekly summary finance reads. Use when the user asks for a week-end report.",
      "path": "skills/write-weekly-summary/SKILL.md",
      "loaded": "metadata"
    }
  ],
  "mcpServers": [
    {
      "id": "invoice-tools",
      "type": "streamable-http",
      "status": "connected"
    }
  ],
  "tools": [
    {
      "name": "query_invoices",
      "server": "invoice-tools",
      "inputSchema": {
        "type": "object",
        "required": ["week"],
        "properties": {
          "week": { "type": "string", "pattern": "^[0-9]{4}-W[0-9]{2}$" },
          "status": { "type": "string", "enum": ["open", "paid", "overdue"] }
        }
      }
    }
  ]
}

Прыжок навыка: frontmatter становится поверхностью открытия

Agent Plugins не переписывает SKILL.md. Правило открытия одно: прямой потомок skills/ с обычным файлом ровно SKILL.md. Спрятанный в skills/deploy/extra/SKILL.md невидим. Навык вне Agent Skills ОБЯЗАН быть пропущен; остальные навыки и MCP грузятся дальше. В контекст попадают name и description из frontmatter плюс путь, чтобы потом дочитать тело, scripts/ и references/.

В описании должны быть и «что делает», и «когда брать». invoice-ops-skill-v2 или слоган от первого лица обнуляют поверхность — ящик стоит, модель не выбирает, пользователи винят плагин. Сломана инструкция. scripts/ по-прежнему значит «запусти этим шеллом»; аргументы — argv, не первоклассные инструменты из tools/list. Имена скриптов не должны попадать в tools[] снимка. Если попали — вложение Skill записали как MCP.

Тело по требованию бережёт окно. loaded: metadata в снимке ловит регрессию «залить весь runbook в системный промпт». Окно, раздутое инструкцией, — баг политики загрузки клиента, не формата Plugin. Спецификация гарантирует только, что навык можно найти. Как показать его модели и пользователю — решает клиент.

Прыжок MCP: подключиться, затем tools/list

mcp.json ОБЯЗАН лежать в корне. Не встраивать в plugin.json и не переносить на другой ядерный путь. На верхнем уровне только $schema и mcpServers. $schema закрепить на https://agent-plugins.org/schemas/1.0.0/mcp.schema.json и сверить с версией спецификации в манифесте. Расхождение гасит только MCP этого плагина. У каждого сервера явный type: stdio, streamable-http или необязательный наследие sse. Транспорт по форме объекта не угадывать. url у streamable-http — абсолютный http/https; вне loopback — https. headers — видимые данные упаковки, не слот для секретов.

Поверхность открытия после соединения — tools/list. Файл упаковки отвечает, куда идти. Контракт инструмента — законны ли arguments этого прыжка. Не копируйте inputSchema в plugin.json и не копируйте name / version в inputSchema. Отказ авторизации — отказ соединения этого сервера, не незаконная конфигурация плагина: переносимых полей OAuth спецификация не задаёт, секреты остаются в рантайме клиента. Провод — в Что такое MCP.

Ниже переносимый фрагмент удалённого MCP. Ключи API в фикстуры репозитория не писать. После соединения залейте tools/list в tools[] снимка. Сбой рукопожатия пропускает только этот сервер; остальные серверы и навыки живут. Эта граница отказа — в спецификации, не в слогане продукта.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "invoice-tools": {
      "type": "streamable-http",
      "url": "https://billing.example.com/mcp"
    }
  }
}

Независимые отказы, фикстуры в JSONVue

Минимум четыре фикстуры ревью: легальный plugin.json выше, снимок способностей, переносимый mcp.json, один объект arguments для query_invoices. Первая ОБЯЗАНА пройти официальный plugin.schema.json. Вторая — ваша схема снимка или структурные ассерты; схему упаковки на неё не натягивать. Третья — mcp.schema.json. Четвёртая — inputSchema инструмента. Четыре JSON, четыре работы: личность, инвентарь, соединение, вызов.

Два отрицательных: name = Invoice-Ops; у одной записи mcp.json убрать type. Первое ОБЯЗАНО отвергнуть пакет. Второе пропускает только этот сервер. Если CI считает неизвестное поле верхнего уровня фатальным, вы строже клиента: спецификация велит сообщить, проигнорировать и продолжить. Секретов в закоммиченных фикстурах быть не должно.

В браузере хватит:Форматирование JSON, чтобы увидеть, парсятся ли манифест, снимок и mcp.json;Проверка JSON Schema, чтобы проверить $schema, name, mcpServers и inputSchema;JSON Diff, чтобы поймать рантайм, записанный обратно в упаковку. Данные с машины не уходят. Дальше:MCP и JSON Schema, обзор Plugins и когда собирать ящик.

Связанное: Google Agent Plugins 2026, Skills vs MCP vs Plugins, MCP и JSON Schema, Что такое MCP.

Частые вопросы

Выводы и дальше

В 2026 фраза «Plugin сам даёт кодирующему агенту умения» сжимается в одну: новое умение — результат открытия, не вес. После пяти прыжков в памяти личность, метаданные навыков и контракты инструментов. Пропущен прыжок — пользователи пишут «поставил, всё равно не умеет».

Выпускать так: прогнать plugin.json через официальную схему; обойти skills/ и mcp.json; заморозить фикстуру снимка; первый tools/call сверить с inputSchema. Четыре контракта оставить в JSONVue. Ящик — текст про Plugins. Собирать ли — текст выбора. Провод — тексты про MCP.