Agent Plugins 1.0.0: The Shared Packaging Format for Skills and MCP Servers

Google, Microsoft, OpenAI, Cursor, Vercel and AWS have put their names behind Agent Plugins 1.0.0, a specification for how plugins for AI agents are packaged. It fixes the directory layout, the configuration file format and the discovery rules for two kinds of components, skills and MCP servers. The stated aim is simple: write a plugin once and run it in any compatible client.

Until now there were two usual ways to give a coding agent new abilities. A skill is a set of Markdown instructions the agent reads when it needs them. An MCP server is a separate process that connects the agent to outside tools, APIs or databases. The contents of both were already portable between tools, yet each tool had its own habits for folder layout, config file names and where files should sit.

Version 1.0.0 deals only with the outer wrapper. It leaves the inside of a skill and the MCP protocol itself alone.

Why it matters

The value shows up for three groups:

• Plugin authors get one directory structure that works in every supporting client. There's no more keeping separate copies for Cursor, Copilot, Codex and the rest.
• Tool vendors get fixed spots for skills/ and mcp.json, so they don't have to invent discovery logic or config parsing. A vendor can still add its own extras inside a namespaced directory without disturbing other implementations.
• The wider ecosystem gains from three design choices: discovery by directory, no setup beyond placing files, and failures that stay contained. Distribution gets easier, and authors can think about what to build instead of which tools to target.

The limits are just as clear. The spec standardizes the package wrapper and says nothing about the safety of what's inside. It has no signatures, no permission model and no handling of secrets. Right now the benefit is developer efficiency, and it doesn't offer security or trust guarantees.

Directory layout

A conforming plugin is only a folder. For an example called reports-plugin, the full tree looks like this:

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

Clients look in exactly three places. plugin.json marks the folder as a valid plugin. Each first-level subfolder of skills/ that holds a SKILL.md counts as one skill. And mcp.json is read as the MCP server configuration. Folders named in reverse-domain style, such as com.cursor.tools/, are read only by the client they belong to, here Cursor. Other clients, ChatGPT and Codex among them, just skip them.

The plugin.json manifest

plugin.json is the only mandatory file, and a minimal one is tiny:

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

The schema is closed, with ten permitted top-level fields: $schema, name, version, description, author, homepage, repository, license, keywords and extensions. An unknown field is reported and ignored, and the plugin still loads. A bad name is another matter. If it's missing, has the wrong type or contains illegal characters (uppercase letters, doubled hyphens, an empty string), the whole plugin is rejected.

The name rules: between 1 and 64 characters, made of lowercase letters, digits, hyphens and periods. It has to start and end with a letter or digit, and two hyphens or two periods in a row are forbidden.

How components are found

Discovery is purely directory-based. plugin.json can't move components elsewhere or embed their configuration inline. Only three kinds of location exist:

• skills/: any first-level subfolder containing a SKILL.md is a skill. Deeper folders aren't scanned.
• mcp.json: the MCP server configuration.
• Client extension folders: named in reverse-domain form such as com.example.client/, and ignored by every other client.

A missing component isn't an error. If skills isn't a directory, or mcp.json isn't a regular file, that component type is flagged invalid while the others load as usual.

MCP configuration

mcp.json needs two top-level fields, $schema and mcpServers. The $schema version has to equal the one declared in plugin.json, otherwise the whole MCP configuration is thrown out.

Three transports are defined:

• stdio runs a local child process. command is one executable token, either a bare name resolved through the system PATH or a plugin-relative path starting with ./. Optional fields are args, env and cwd, and cwd defaults to the plugin root.
• streamable-http is the current MCP Streamable HTTP standard.
• sse is the older HTTP+SSE transport from the 2024-11-05 MCP spec, kept for backward compatibility.

Clients must implement stdio or streamable-http at minimum, and both is better. sse is optional.

Environment variables and persistent data

Whenever a client launches a stdio process, it must set two variables. PLUGIN_ROOT holds the absolute path to the plugin's root folder. PLUGIN_DATA points to a persistent data directory the client provides, which survives plugin updates and is removed on uninstall.

Both ${PLUGIN_ROOT} and ${PLUGIN_DATA} may appear in args, in env values and in cwd. Substitution is a single plain-text pass. No other placeholders and no shell-style variable expansion are supported.

Failures stay local

The spec applies a "partial failure must not cascade" rule at several levels:

• One MCP server failing to start doesn't affect other servers or skills.
• A skill with broken formatting is skipped while the rest load normally.
• An MCP entry using a transport the client doesn't support is skipped.
• If mcp.json is completely invalid, only MCP components are turned off, and skills still load.

What the spec leaves out

Missing from version 1: how plugins get installed, runtime permission control, author authentication and secure storage of secrets or API keys. The text says outright that header values and environment values are visible package data and not a portable way to keep things confidential. There's also no OAuth configuration and no portable credential reference field, so authorization has to be handled by each client in its own way.

Who's in, and who isn't

Launch support covers six clients: Kiro, VS Code, Cursor, GitHub Copilot, Codex and ChatGPT. Google signed on as a maintainer the same day, and its Agents CLI is among the first products to adopt the format. AWS is a supporter as well.

Anthropic created both the skills format and MCP, and Claude Code has used a nearly identical plugin packaging since 2025. Even so, Anthropic wasn't part of the working group, and Claude Code isn't on the initial support list.

An end-to-end example with Google's Agents CLI

Agents CLI is one of the early adopters. Once installed, it gives a coding agent seven skills that cover ADK patterns, project scaffolding, evaluation, deployment and observability.

Consider building a RAG knowledge assistant. A developer describes the goal in plain language, and the agent proceeds on its own:

1. It scaffolds the project from the ADK agentic_rag template, with Vector Search as the data store.
2. It notices the template lacks citation support, rewrites the agent instructions to demand inline citations and changes the retriever to return source IDs.
3. It sets up the data store, loads 12 Python reference documents as the corpus and runs a smoke test.

An evaluation runs before deployment: 20 test cases in four groups, 6 for retrieval accuracy, 5 for refusing when context is lacking, 5 for multi-hop reasoning and 4 for citation accuracy.

The evaluation exposed one edge case that caused hallucination. For questions beyond the corpus, the agent sometimes answered from general knowledge instead of admitting it didn't know. The cause was a single sentence in the system prompt saying that simple questions with a known answer can be answered directly without tools. Deleting that sentence fixed it completely.

Deployment to Google Cloud takes two to three minutes, with Cloud Trace on by default. After registering with Gemini Enterprise, everyone in the organization can find and use the agent.