Six Major Vendors Release Unified AI Agent Plugin Packaging Standard

Specification Overview

Google, Microsoft, OpenAI, Cursor, Vercel and AWS released the Agent Plugins 1.0.0 specification, which standardises the outer packaging of AI Agent plugins while leaving the internal skill format and MCP protocol unchanged. The goal is a “write once, run on any client” experience.

Directory Structure

A compliant plugin is a single folder. Example reports-plugin layout:

reports-plugin/
├── plugin.json                  # required entry point
├── skills/                      # optional collection of skills
│   ├── summarize/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── analyze.sh
│   │   └── references/
│   │       └── checklist.md
│   ├── deploy/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── rollback.sh
│   │   └── references/
│   │       └── runbook.md
│   └── code-review/
│       └── SKILL.md
├── mcp.json                     # optional MCP server configuration
├── com.cursor.tools/            # optional client‑specific extensions
│   └── hooks/
│       └── hooks.json
├── LICENSE
└── CHANGELOG.md

Clients recognise three fixed locations: plugin.json – validates the package. skills/ – each immediate subdirectory containing a SKILL.md is treated as a skill; deeper recursion is not performed. mcp.json – MCP server configuration.

Namespaced directories such as com.cursor.tools/ are read only by the matching client; other clients ignore unknown prefixes. Standard files like LICENSE and CHANGELOG.md are not part of the spec.

plugin.json Specification

The sole required file. Minimal example:

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

The schema is closed‑set and permits exactly ten top‑level fields: $schema, name, version, description, author, homepage, repository, license, keywords, extensions. Unknown fields are reported and ignored but do not block loading. The name field is mandatory; it must be 1‑64 characters, lower‑case letters, digits, hyphens and periods only, start and end with a letter or digit, and contain no consecutive hyphens or periods. Invalid or missing name causes the plugin to be rejected.

Component Discovery

skills/

: any immediate subdirectory with a SKILL.md becomes a skill; no recursive scanning. mcp.json: MCP configuration file.

Client‑specific extension directories named with reverse‑domain notation (e.g., com.example.client/) that only the matching client reads.

If a component is missing, it is not an error. If skills is not a directory or mcp.json is not a regular file, that component type is marked invalid while the remaining components continue loading.

MCP Configuration

mcp.json

must contain the top‑level fields $schema and mcpServers. The $schema version must match the one declared in plugin.json; a mismatch invalidates the entire MCP configuration.

Supported transport types:

stdio : local subprocess communication. command is a single executable token, either a bare name (found via PATH) or a relative path prefixed with ./. Optional fields args, env, cwd are allowed; cwd defaults to the plugin root.

streamable-http : the current MCP Streamable HTTP transport.

sse : deprecated HTTP+SSE transport (spec version 2024‑11‑05) retained for compatibility.

Clients must support at least stdio or streamable-http; supporting both is recommended. sse is optional.

Environment Variables and Data Persistence

When launching a stdio subprocess, the client provides two environment variables: PLUGIN_ROOT: absolute path to the plugin’s root directory. PLUGIN_DATA: a persistent data directory allocated by the client; contents survive plugin updates and are removed on uninstall.

Both placeholders may be used in args, env values and the cwd field via simple, non‑recursive text substitution. No other placeholders are supported.

Local Failure Isolation

If a single MCP server fails to start, other servers and skills continue loading.

If a skill’s format is invalid, that skill is skipped while the rest load.

If a transport type is unsupported, the corresponding MCP entry is ignored.

If mcp.json is wholly invalid, only the MCP component is disabled; skills still load.

Uncovered Areas

The specification deliberately excludes installation mechanisms, runtime permission control, author authentication, key management, and secure storage of API tokens. Header and environment values are described as “visible package data, not a portable secret mechanism”. OAuth configuration and portable credential references are not defined; each client must manage its own authorization flow.

Supported Clients

First‑wave clients that implement the spec include ChatGPT, Codex, Cursor, GitHub Copilot, Kiro, VS Code, Google (as a maintainer with the Agents CLI) and AWS.

The skill format and MCP protocol were created by Anthropic. Claude Code uses an almost identical packaging format since 2025, but Anthropic is not part of the standard‑setting group and Claude Code is not listed among the initial supported tools.

Practical Example – Full Agents CLI Workflow

Google’s Agents CLI, one of the earliest adopters, injects seven skills covering ADK mode, project scaffolding, evaluation, deployment and observability.

Use the ADK agentic_rag template to create a project structure with Vector Search as the data store.

The template lacks a reference hook; the Agent rewrites its instruction to inline the reference and adjusts the retriever to return source IDs.

Configure the data store, import twelve Python‑basic corpus entries, and run a smoke test.

Before deployment, an evaluation runs 20 test scenarios split into four categories: 6 for retrieval correctness, 5 for insufficient‑context refusals, 5 for multi‑hop reasoning, and 4 for citation accuracy.

An hallucination edge case appears when out‑of‑corpus questions receive commonsense answers instead of refusals. The root cause is a system instruction line—“If you already know the answer to a simple question, you may answer without using tools”—which, when removed, resolves the issue.

Deployment to Google Cloud takes 2–3 minutes with Cloud Trace enabled by default. After registering the Agent with Gemini Enterprise, all organization members can discover and use it.

Related Links

Specification document: https://agent-plugins.org/specification

GitHub repository: https://github.com/agentplugins/agent-plugins-spec