feat: Support Google Agent Plugins specification for packaging skills and MCP servers

[aheritier]

Overview

Agent Plugins 1.0.0 is an open, vendor-neutral specification for packaging Agent Skills and MCP servers into portable, reusable plugins. The spec was published by a Technical Steering Committee (TSC) with contributors from Amazon, Cursor, Microsoft, OpenAI, Vercel, and Google.

What Are Google Agent Plugins?

Agent Plugins solve a core packaging problem: when a developer builds a skill and MCP server that work together, they today must maintain different versions for each AI client (IDE, CLI, managed platform) because each client has its own manifest format, directory structure, and MCP configuration shape. Agent Plugins provide one standard wrapper that works across all compatible clients.

Directory Structure

A plugin is a directory with a predictable, fixed layout:

reports-plugin/
├── plugin.json         # minimal manifest (name + schema ref)
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json            # MCP servers with explicit transport type
└── com.example.client/ # client-specific extensions (reverse-domain)

Manifest (plugin.json)

Intentionally minimal — only two required fields:

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

Key Design Principles

• Fixed locations: no guessing of paths, no precedence rules to learn
• Explicit transports: mcp.json always declares stdio, Streamable HTTP, or legacy HTTP+SSE — never inferred from config shape
• Independent failure: a failed MCP server does not take down the plugin's skills
• Client extensions: reverse-domain namespace (com.example.client/) for client-specific hooks; unknown extensions are silently ignored
• Scope-limited by design: no install mechanism, no distribution protocol, no permission model — those are intentionally left to client-specific layers above

Ecosystem Layers

Agent Plugins sit within a layered ecosystem:

1. Find it — Agentic Resource Discovery (ARD)
2. Describe it — AI Catalog (recognizes application/agent-plugins+json)
3. Package it — Agent Plugins ← this spec
4. Run it — MCP + Agent Skills

Why This Matters for docker-agent

docker-agent already supports agent config YAML with MCP server references and agent skills. Adding Agent Plugins support would:

1. Expand the plugin ecosystem: Users could consume any Agent Plugins-compatible package (e.g. Google's Agents CLI, Data Agent Kit for BigQuery/Spanner/Cloud SQL) directly in docker-agent without adapters.
2. Publish docker-agent agents as plugins: docker-agent agent configs could be exported/distributed as Agent Plugins, making them portable to Cursor, Claude Code, Gemini CLI, and other compatible clients.
3. Align with emerging standards: The spec has buy-in from major AI tooling vendors; early adoption positions docker-agent as a first-class citizen in this ecosystem.
4. Simplify multi-client distribution: A single docker-agent skill or MCP bundle could be packaged once and consumed across all compatible clients — directly addressing a gap in the current OCI-based share workflow.

Acceptance Criteria / Implementation Notes

Loading / consuming Agent Plugins

• Detect and load a local Agent Plugin directory (presence of plugin.json with valid schema ref)
• Parse skills/ subdirectories according to the Agent Skills spec
• Parse mcp.json and register MCP servers declared therein (honour explicit transport types)
• Ignore unknown client-extension directories (com.<vendor>.*) gracefully
• Handle independent MCP server failures without aborting skill loading

Publishing / exporting as Agent Plugins

• Add an export command (e.g. docker-agent share export --format agent-plugin) that generates a compliant plugin directory from an agent config
• Generate a valid plugin.json from agent metadata
• Map inline MCP server config to mcp.json with explicit transport fields
• Map skills/prompts to skills/<name>/SKILL.md

Config schema

• Add plugins: array to agent config YAML (latest schema only) to reference local or remote Agent Plugin directories
• Update agent-schema.json accordingly

Documentation & examples

• Add an example YAML demonstrating plugin consumption
• Document the mapping between docker-agent concepts and Agent Plugin components

References

• Blog post: https://developers.googleblog.com/agent-plugins-package-your-skills-tools-and-more/
• Full specification: https://agent-plugins.org/specification
• Compatible clients list: https://agent-plugins.org/compatible-clients
• GitHub spec repo: https://github.com/agentplugins/agent-plugins-spec
• Google Agents CLI (reference implementation): https://google.github.io/agents-cli/guide/getting-started/
• Data Agent Kit (Google Cloud plugins): https://github.com/GoogleCloudPlatform/data-agent-kit