The agent plugin standard, and what actually travels between tools

You wrote something once and it worked. A folder of instructions that tells an agent how your quotes are numbered, which clauses you never soften, and what a finished draft looks like. Maybe a small MCP server that reads your booking system. Then you opened a different tool, dropped the same folder in, and nothing happened. The instructions were fine. The packaging around them was not.

Since 6 August 2026 there is a published answer to that exact problem. Agent Plugins 1.0.0 is a specification for how an extension directory is laid out, refined by representatives of AWS, Anysphere, GitHub, Microsoft, OpenAI and Vercel [3]. It is much smaller than the name suggests, and knowing how small is the part that saves you time. This guide is for people who write skills, or run MCP servers, that more than one tool or more than one person uses. If you only install other people’s plugins from a marketplace, the standard changes nothing you can see, and you can stop reading here.

The portable thing is a folder with SKILL.md in it

Before any of the plugin packaging, there is the skill. A skill is a directory containing a SKILL.md file: YAML frontmatter, then instructions in Markdown [6]. Two fields are required. name is 1 to 64 characters, lowercase letters, numbers and hyphens only, and it must match the parent directory name. description runs up to 1,024 characters and should say both what the skill does and when to use it [6]. Optional fields are license, compatibility (up to 500 characters, for environment requirements), metadata, and the experimental allowed-tools [6].

The loading behaviour explains why the description matters more than the body. At startup an agent reads only each skill’s name and description, roughly 100 tokens. It reads the full SKILL.md only once a task matches, and files under scripts/, references/ and assets/ only when the instructions point at them [6]. The spec recommends keeping the body under 5,000 tokens and SKILL.md under 500 lines, moving detail into referenced files [6]. A vague description means the skill is never picked up; a bloated body means it costs context every time it is.

This format is read directly by clients, with no plugin wrapper at all. Codex scans .agents/skills in every directory from your working directory up to the repository root, plus $HOME/.agents/skills and /etc/codex/skills [7]. Claude Code reads skills/<name>/SKILL.md from a plugin root, and will load a single skill placed as SKILL.md at the root [4]. You can check a folder before you ship it with skills-ref validate ./my-skill [6].

The standard is a rule about where files sit, not what they contain

An Agent Plugins package is a directory with plugin.json at its root. The manifest has exactly two required fields: $schema, set to https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, and name. Everything else is optional metadata such as version, description, author, homepage, repository, license, keywords and extensions [1].

The rest of the contract is the directory layout. Skills live in skills/ as subdirectories containing SKILL.md. MCP servers are configured in mcp.json at the plugin root, and when it is present the version in its $schema must match the version plugin.json declares. Clients must find components only in those fixed locations, and inline component configuration inside plugin.json is not allowed [1]. mcp.json covers three transports: stdio for a local executable, streamable-http, and the legacy sse transport, which clients may support or not [1].

Two details bite in practice. A client launching a stdio server must set PLUGIN_ROOT to the plugin directory and PLUGIN_DATA to a persistent data directory it manages, and only those two placeholders are expanded, only inside args, cwd and the values in env, never in command or in env keys [1]. And failure is graded: a missing component location is not an error, a broken server entry is skipped while the rest load, but any schema violation other than an unknown top-level field or a non-object extensions is fatal to the whole plugin [1]. So the work of adopting the standard is renaming and moving, not rewriting.

Everything a client invented for itself stays behind

Version 1 covers two component types, Agent Skills and MCP servers, because those already had their own specifications and adoption [3]. Commands, hooks, agents, rules and LSP servers are explicitly out of scope and remain client-specific [1].

Hold that list against what a Claude Code plugin can contain. Its manifest sits at .claude-plugin/plugin.json, and the plugin root can also hold commands/, agents/, hooks/hooks.json, .lsp.json for language servers, monitors/monitors.json for background watchers, bin/ for executables added to the agent’s PATH, and a settings.json that can activate one of the plugin’s own agents as the main thread [4]. Only the skills/ directory and the MCP configuration from that list have any equivalent in the standard.

The spec’s answer for the rest is a reverse-domain namespace directory, such as com.example.client/, where a client keeps its own material [1]. VS Code keeps Copilot-specific agents, commands, rules and hooks in a com.github.copilot directory at the plugin root, and the point of that namespace is that other clients ignore it, so the package stays portable while keeping its Copilot capabilities [5]. That is a way to keep the non-portable half in the same package without breaking anyone else. It is not a way to make it portable.

One directory can carry two manifests at once

The formats do not collide, which is the useful accident here. Claude Code looks for .claude-plugin/plugin.json and .mcp.json [4]. The standard looks for plugin.json and mcp.json at the root [1]. Different names, different locations, and both read skills/<name>/SKILL.md. So you add the standard’s manifest to a working plugin rather than converting it, and nothing that worked yesterday stops working.

One directory that satisfies both looks like this, with the skill text written once and two thin manifests over it:

my-plugin/
├── plugin.json            # Agent Plugins: $schema + name
├── mcp.json               # Agent Plugins: MCP servers
├── skills/
│   └── quote-review/
│       ├── SKILL.md
│       └── references/
├── .claude-plugin/
│   └── plugin.json        # Claude Code manifest
├── .mcp.json              # Claude Code MCP config
└── com.github.copilot/    # Copilot-only agents, hooks, commands, rules

The two manifests carry the same name and version and little else, because in both formats the manifest is metadata and the directory layout is the contract [1][4]. The duplication that remains is a few lines of JSON, not a second copy of the thing you actually wrote.

VS Code makes this concrete. It detects a plugin’s format from the root manifest: a plugin.json carrying the Agent Plugins $schema is treated as Agent Plugins 1.0, a plugin.json with no schema declared is treated as the Copilot format, .claude-plugin/plugin.json is treated as the Claude format, and .plugin/plugin.json as legacy OpenPlugin [5]. VS Code says it continues to support the Copilot, Claude and legacy OpenPlugin formats, and that Copilot-format and Claude-format plugins provide the same capabilities from different locations [5]. A Claude-format plugin therefore already loads there, unconverted. Adding the root plugin.json is what buys you the clients that only read the standard.

Test locally before you publish anything. Claude Code takes claude --plugin-dir ./my-plugin, reloads with /reload-plugins, and checks structure with claude plugin validate ./your-plugin [4]. VS Code registers a local directory through the chat.pluginLocations setting, with chat.plugins.enabled controlling the feature [5].

Conformance is a range, not a promise

A client can claim conformance while supporting only one of the two component types. The minimum bar is parsing and validating plugin.json, discovering components from the fixed locations, and supporting skills or MCP, not both. If it does support MCP it must implement stdio or Streamable HTTP [1]. So “compatible” describes a range of behaviours rather than a guarantee that your package works [8].

The published list of compatible clients currently runs to nine, including VS Code, Cursor, GitHub Copilot, ChatGPT and Codex, and Kiro. All nine load Agent Skills, all nine take MCP over stdio and Streamable HTTP, and seven also accept the legacy SSE transport; ChatGPT and Codex is one of the two that does not [2]. Check that table for your specific targets before you promise a colleague their tool is covered.

Three gaps are worth knowing before you build on this. There is no portable credential mechanism; the spec prohibits embedding credentials and offers no standard way to supply them, so anything authenticated is still configured per client. Clients differ in whether they inherit, drop or sanitise environment variables, so an identical plugin can behave differently across two machines. And the published JSON schema contradicts the normative text on how unknown fields are handled, which means validators can disagree [8].

Whether it is worth doing at all

If one tool loads your extension and that is the whole story, do nothing. Keep the skill in a clean skills/<name>/SKILL.md folder with a good description, and you already own the part that survives a switch. The standard buys you nothing until a second client is involved.

The cost it removes is duplicate packaging: the same instructions maintained in two or three shapes, each edited whenever the underlying process changes. That is the number to check before you spend a morning on this.

If the number is small but not zero, do the cheap half. Pull the instructions out of wherever they currently live into a skills/<name>/SKILL.md folder with a description that says when to use it, and stop there. That folder is already loadable by every client on the compatible list [2] and by clients that read skills without any plugin wrapper at all [7]. The root plugin.json takes minutes and can wait until the day a second tool is actually in front of you.

What still goes wrong

The company that wrote both halves of the standard is not in the room. Anthropic authored MCP and the Agent Skills format, and holds no seat on the Technical Steering Committee, whose maintainers come from Amazon, Cursor, Microsoft, OpenAI and Vercel, with a Google maintainer named as joining [8]. Claude Code is absent from the compatible-clients list [2], and its own plugin documentation does not mention the standard [4]. Nothing stops you shipping a folder both formats read, and VS Code will load the Claude layout regardless [5], but the governance of the format you are standardising on does not include the tool many readers use every day.

Portability of files is not portability of behaviour. The same SKILL.md handed to two different models produces two different results, and the standard has nothing to say about that. It moves your instructions; it does not move the judgment applied to them. Budget time to re-test the actual output in each tool, not just to confirm the skill loaded.

Finally, this is a young specification with known holes. There is no permission declaration, no cryptographic signing, no attestation chain and no conformance test suite yet [8]. Installing a plugin still means running a stranger’s code with your agent’s access, and a shared manifest format does not make that safer. Read what you install, or keep to packages your own team wrote.