The Agent Plugins Specification is the normative document behind the packaging format published on August 6, 2026 by a group of agent-client vendors. It describes itself as "the complete normative contract for portable Agent Plugin packages and conformant clients" and defines "version 1.0.0 of the Agent Plugins format." The topic page is Agent Plugins 1.0.0.
The document carries two status markers that do not obviously agree: Spec Version: 1.0.0 and Status: Working Draft. Both are stated on the specification page itself. A version number that reads as a frozen release sits alongside a status that reads as pre-release, and the specification does not reconcile them; conformance language is nonetheless framed as binding — "Clients and plugin packages claiming conformance to Agent Plugins v1 MUST implement or follow the requirements in this document."
Normative structure
Eleven sections are normative: status and version, conformance language, terminology, plugin package model, manifest, component discovery, component types, client extensions, environment variables and placeholder expansion, versioning, and client conformance. Two further pieces — Appendix A (a conformance checklist) and a Design Decisions section — are marked explicitly non-normative, and the appendix carries its own precedence rule: "when it conflicts with the spec text above, the spec governs."
Section 2 fixes the conformance vocabulary: MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL "are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals." This section is what makes "conformant client" a checkable property rather than a marketing description, and is the citable part of the document.
Governance is deliberately held outside the format: section 1.1 states that governance "is defined separately from the portable package format in the Technical Charter," which lives in the project's public repository.
Scope boundary
The specification's scope is packaging and discovery, and it says so by exclusion rather than by claim. Section 7 states that "Agent Plugins v1 defines exactly two component types: skills and MCP servers. Other component types are outside the v1 format and do not affect conformance." Section 7.1 disclaims the skill format itself: Agent Skills "MUST conform to the Agent Skills specification," which "is the source of truth for the SKILL.md format, frontmatter fields, and directory layout," and this document "defines how Agent Skills are discovered within a plugin, not the skill format itself or how clients expose skills to users or models." Section 7.2 makes the parallel disclaimer for MCP: the Model Context Protocol specification "defines MCP wire behavior and lifecycle semantics," while Agent Plugins defines only "the mcp.json configuration format used to locate and connect to MCP servers."
The Design Decisions section explains the boundary: v1 covers Skills and MCP "because both have established specifications outside this project and meaningful cross-client adoption," while "commands, hooks, agents, rules, and LSP servers — remain too client-specific for a stable portable contract and are outside the v1 format until their formats converge."
Two further exclusions are stated directly. On credentials: "Agent Plugins v1 defines no OAuth configuration or portable credential-reference fields. Authorization discovery, user interaction, and credential storage are client-managed." On sandboxing: the containment rules "do not sandbox a plugin subprocess or restrict paths supplied at runtime." Nothing in the document addresses marketplaces or distribution.
Package model and manifest
A plugin is "a directory rooted at a single filesystem location" and "MUST include a manifest at plugin.json in the plugin root." Path containment is the model's principal safety rule: any file or directory a client reads or executes from the package "MUST remain within the filesystem-resolved plugin root," symlinks may resolve only to targets inside it, and any configuration field defined as a plugin-relative path "MUST begin with ./." Command arguments and environment values are treated as opaque strings that clients "MUST NOT interpret as package paths."
Containment failures are graded by a narrowest-applicable-boundary rule: an unresolvable plugin.json rejects the plugin; a bad fixed component location invalidates that component type; a bad SKILL.md skips that skill; a bad MCP command or cwd invalidates that server entry; anything else denies access to the path.
The manifest schema is closed. Only ten top-level fields are permitted: $schema, name, version, description, author, homepage, repository, license, keywords, and extensions. Only $schema and name are required. Unknown top-level fields and a non-object extensions field are non-fatal — clients "MUST report and ignore" them and continue loading — while "any schema violation other than an unknown top-level field or a non-object extensions field is fatal." Plugin names are constrained to 1–64 characters of lowercase alphanumerics, hyphens and periods, alphanumeric at both ends, with no consecutive hyphens or periods.
Clients "MUST NOT retrieve a schema while loading a plugin"; $schema is a version selector resolved against locally supported rules, not a fetch instruction. Where the schema and the prose disagree, "the specification text is authoritative."
Component discovery
Discovery locations are fixed and cannot be redirected: skills from skills/ (immediate child directories containing a SKILL.md regular file, with no recursive search deeper), MCP servers from mcp.json at the plugin root. "plugin.json cannot override these locations or contain inline component configuration." A missing location is not an error; a location present but of the wrong filesystem kind invalidates that component type while other types continue loading.
The mcp.json format is a closed union keyed on type: stdio (with command, args, env, cwd), and streamable-http or sse (with url, headers). command "MUST contain a single executable token, not a shell command string," either a bare name or a ./-prefixed plugin-relative path, and is not subject to placeholder expansion. Remote URLs must be absolute HTTP or HTTPS without user information or fragment, and "non-loopback endpoints MUST use HTTPS." Headers are described as "visible package data, not a portable secret mechanism," and plugins "MUST NOT embed credentials or other secrets" in either headers or env.
A client supporting MCP servers "MUST support at least one of stdio or streamable-http and SHOULD support both"; sse support is optional and refers to the deprecated HTTP+SSE transport of the MCP 2024-11-05 specification, not to SSE streams inside Streamable HTTP.
Client extensions
Client-specific data is confined to reverse-domain namespaces: manifest data under extensions, files under a top-level directory named exactly for the namespace (for example com.example.client/). The specification "assigns no portable discovery, validation, loading, or failure semantics to client extension data or files" — each client defines its own namespace's contents and behaviour. A client "MUST ignore manifest entries for namespaces it does not implement without validating the contents of their values."
Runtime environment
Clients that launch plugin subprocesses "MUST provide PLUGIN_ROOT and PLUGIN_DATA in each subprocess environment." PLUGIN_ROOT is the absolute resolved plugin root; PLUGIN_DATA is "a client-managed persistent data directory dedicated to that installed plugin instance," which the client must create before launch, make writable, and "MUST preserve its contents across plugin updates." The intended split is stated: PLUGIN_DATA for installed dependencies, generated code, caches and state that outlive an update; PLUGIN_ROOT for bundled scripts, binaries and config files.
Expansion is deliberately minimal — "a single, non-recursive textual replacement of every exact occurrence of either placeholder," applied only to args elements, env values and cwd, never to env keys or command. "Text introduced by a replacement MUST NOT be scanned for further placeholders," unrecognized placeholder-like text stays literal, and "clients MUST NOT perform any other placeholder or environment-variable expansion." A server env object containing PLUGIN_ROOT or PLUGIN_DATA is invalid; the client supplies those itself, after overlaying configured env.
Versioning and conformance
Section 10 ties the manifest schema, the MCP schema and the specification to a single version: "Every specification release MUST publish both schemas with the same version as the specification, even when a schema's validation rules are unchanged." An mcp.json whose $schema version differs from the one in plugin.json invalidates the MCP configuration but not other component types. Published canonical schema identifiers "MUST NOT be reassigned to different schema contents." Plugins "SHOULD use Semantic Versioning" for their own version, which clients may use for update checks and cache freshness.
The conformance floor in section 11.1 is eight items, ending with "supports at least one component type (skills or MCP servers)." Section 11.2 makes partial support explicit: "a skills-only client can conform without supporting MCP servers." Failure isolation is a conformance requirement rather than a recommendation — "a failure isolated to a component type, component entry, or component process MUST NOT prevent the client from loading independently valid components" — and lack of support for a component type, transport or extension "is not itself an error."
Design rationale recorded in the document
The non-normative Design Decisions section states the reasoning behind several choices: directories rather than archives, so plugins stay "inspectable with standard tools (ls, cat, git), editable in-place during development, and compatible with version control"; a closed manifest, to enable "strict validation, typo detection, and schema-driven key completion" while containing client experiments under extensions; reverse-domain namespaces as "a decentralized convention for avoiding collisions without requiring a central client-name registry"; an explicit MCP configuration format because "existing clients use incompatible MCP configuration shapes and infer transports differently"; single-transport clients because stdio and Streamable HTTP "serve different deployment and security models" and requiring both "would expand its implementation and trust surface"; and non-fatal component failures because "a plugin that provides skills and an MCP server should not become entirely unusable because one server is unavailable."
Provenance
Retrieved on August 9, 2026 from agent-plugins.org/specification, the project's own canonical publication site, with the machine-readable schemas served under agent-plugins.org/schemas/1.0.0/ and development carried out in the public repository github.com/agentplugins/agent-plugins-spec. The document carries no DOI or docket identifier, which is the reason Agent Plugins 1.0.0 was set to medium confidence at creation; the specification text itself is unambiguous and self-identifying, so this page is rated high on the contents of the document while the surrounding facts of authorship and adoption rest on the vendor announcements cited at the topic page.
Relationships
- supports: Agent Plugins 1.0.0 — the topic page.
- depends-on: Model Context Protocol (MCP) — one of the two component types; the specification defers all wire and lifecycle semantics to it.
- depends-on: Agent Skills — the other component type, whose format is defined by a separate specification the document treats as the source of truth.
- related: Agentic AI, Agent Architecture Patterns, Agent Supply Archetypes (BYO/Bowling-Shoe × Horizontal/Vertical) — the extension ecosystem the format packages for.
- related: OpenAI, Microsoft — organisations on the Technical Steering Committee, alongside AWS, Cursor and Vercel.