# 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: [[AI Agent Skills|skills]] and [[Model Context Protocol (MCP)|MCP servers]]. A skill pack gets wrapped once for [[Claude Code Plugins|Claude Code]], again for [[Cursor]], again for [[GitHub Copilot]], again for [[OpenAI Codex|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: ```text 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, [[AI Subagents|subagents]], rules and [[Language Server Protocol (LSP)|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 [[Claude Code Hooks|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 and had about 1,350 stars in October 2026. 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 [[Visual Studio Code (VSCode)|VS Code]], the [[GitHub Copilot CLI|Copilot CLI]] and the [[GitHub Copilot App|Copilot app]], and ChatGPT, Codex, [[Hermes Agent]], [[OpenClaw]], Cursor and [[Grok]] were on the list as well (see [[2026-08-19 Agent Plugins - one package format for skills and MCP servers|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 Specification (ARD)|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 - Site: https://agent-plugins.org/ - Repository: https://github.com/agentplugins/agent-plugins-spec - Specification 1.0.0: https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md - Specification 1.1.0 (working draft): https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.1.0.md - Technical Charter: https://github.com/agentplugins/agent-plugins-spec/blob/main/GOVERNANCE.md ## Related - [[Claude Code Plugins]] - [[AI Agent Skills]] - [[Model Context Protocol (MCP)]] - [[AGENTS.md (File Convention)]] (another cross-vendor convention for coding agents) - [[Agentic Resource Discovery Specification (ARD)]] - [[APM (AI)]] - [[2026-08-19 Agent Plugins - one package format for skills and MCP servers]] - [[AI Skill Portability]] - [[AI Skill Distribution]] - [[AI Agent Portability]]