Sign in Subscribe
news

Agent Plugins Specification

Sebastien Dubois

Sebastien Dubois

— 4 min read

This is a note from my public notes. View the canonical version: Agent Plugins Specification.

Agent Plugins is an open, vendor-neutral specification for packaging what extends AI Agents into a single portable directory. Version 1.0.0 is the current release and 1.1.0 is a working draft. Code and schemas are under the Apache 2.0 License, the documentation under CC-BY-4.0.

Every agent client invented its own plugin format, even though the plugins mostly carry the same two things: skills and MCP servers. A skill pack gets wrapped once for Claude Code, again for Cursor, again for GitHub Copilot, again for Codex... Same content each time. Agent Plugins defines one wrapper that any compliant client can load.

What a plugin looks like

A plugin is a plain directory. The smallest valid one holds a manifest and one skill:

hello-plugin/
├── plugin.json
└── skills/
    └── greet/
        └── SKILL.md
  • plugin.json sits at the root and is the only manifest. Two fields are required: $schema, which pins the spec version (e.g. https://agent-plugins.org/schemas/1.0.0/plugin.schema.json), and name (lowercase letters, digits, hyphens and periods, 1 to 64 characters). Optional metadata: version, description, author, homepage, repository, license, keywords. The schema is closed: clients report unknown top-level fields and ignore them.
  • skills/ holds one folder per skill, each with a SKILL.md that follows the AI Agent Skills spec. Clients only look at the immediate subfolders (no recursive search).
  • mcp.json at the root declares MCP servers. Each entry picks exactly one transport: stdio for a local process, streamable-http, or the deprecated sse.
  • Client extensions live under a reverse-domain namespace such as com.example.client, both in the manifest's extensions field and as a top-level folder of the same name. Hooks, commands and anything else vendor-specific go there, so the portable core stays clean.

Locations are fixed. The manifest can't point somewhere else and can't inline component configuration. Fewer options means less for each client to get wrong.

Safety and failure rules

  • Every file the plugin references must resolve inside the plugin root, symlinks included. ../bin/server is invalid.
  • An MCP command is a bare executable name or a ./ path, with args passed separately, so clients never have to parse a shell string someone typed.
  • Clients hand stdio servers two reserved variables: PLUGIN_ROOT (the bundled files) and PLUGIN_DATA (a writable folder that survives updates, for node_modules, virtual environments and caches). Only ${PLUGIN_ROOT} and ${PLUGIN_DATA} get expanded, and only in args, env and cwd.
  • env values and HTTP headers are visible package data, and plugins MUST NOT put credentials there. Authentication, OAuth included, stays with the client.
  • A broken MCP server or an invalid skill gets skipped and reported while the rest of the plugin loads. Only an invalid manifest takes the whole plugin down.
  • A client that only supports skills can still be conformant.

What it leaves out

Version 1 standardizes exactly two component types: skills and MCP servers. Commands, hooks, subagents, rules and LSP servers stay out on purpose; the spec says their formats are still too client-specific to agree on. Distribution, installation, permissions and UX are out of scope too. Agent Plugins defines what a package contains, and getting it onto a machine stays each client's job (marketplace, installer, CLI).

For Claude Code Plugins, that's a real cut. Claude Code keeps its manifest in .claude-plugin/plugin.json and bundles slash commands, subagents and hooks next to skills and MCP servers. Under Agent Plugins, only the skills and the MCP servers are portable; the rest would move into a Claude Code extension namespace.

Who's behind it

The Technical Steering Committee: Clare Liguori (Amazon), Roshan Sadanani (Cursor), Harald Kirschner (Microsoft), Gav Verma (OpenAI) and Jonathan Hefner (Vercel, Lead Core Maintainer). The GitHub repository was created on 2026-04-03. Discussions happen on GitHub Discussions and Discord.

Anthropic is NOT on the committee. A bit ironic, since Claude Code plugins popularized this kind of bundle and the Agent Skills format came out of Anthropic.

When 1.0 landed in August 2026, GitHub Copilot shipped support in VS Code, the Copilot CLI and the Copilot app, and ChatGPT, Codex, Hermes Agent, OpenClaw, Cursor and Grok were on the list as well (see my news post).

My opinion

Limiting v1 to what has already converged (skills and MCP) and pushing the rest into namespaces is the right call. A spec that tried to cover hooks and agents on day one would stall for years.

I maintain hundreds of AI Skills for the Obsidian Starter Kit, and turning them into agent plugins is on my task list. One format that several clients read saves me a wrapper per client.

I see two risks. Microsoft's own APM (AI) and other manifests compete for the same job. And Anthropic is absent: if Claude Code never reads a root plugin.json, authors who target it will keep shipping two manifests.

Agent Plugins pairs well with the Agentic Resource Discovery spec. Agent Plugins defines how you package capabilities; ARD defines how an agent finds them when it needs them. My own vault already serves its skills through a local ARD registry instead of loading them all upfront, and I'd like clients to support both.

References

About Sébastien

Ready to get to the next level?

Found this valuable? Share it with someone who needs it.

Join 6,000+ readers. Get practical systems for knowledge & AI. Free.

Subscribe ✨

Free: Knowledge System Checklist

A clear roadmap to building your own knowledge system. Subscribe and get it straight to your inbox.

6,000+ readers. No spam. Unsubscribe anytime.

Subscribe