Agent Plugins Specification 1.0.0: A Portable Package Format for Skills and MCP Servers

The packaging gap Agent Plugins 1.0.0 targets

Agent extensions have been shipping as loose conventions rather than as packages. A skill is a markdown file with YAML front matter; an MCP server is a process a client launches. Neither has a standard way to say "these belong together, here is the entry point, here is the version." The result is that a skill written for one client has to be re-wrapped for the next one, and an MCP server has to be re-described in each client's own config format. Agent Plugins is an open, vendor-neutral standard for packaging reusable components that extend AI agents into distributable plugins, and it defines a portable package format for Agent Skills and MCP servers. The audience is anyone distributing agent extensions to more than one host: skill authors, MCP server maintainers, and the client teams that have to load third-party code. The scope is narrow on purpose. The README describes itself as a non-normative introduction and points to the versioned specification as the actual contract, which is a useful signal about where the authority sits.

What plugin.json and the skills/ tree actually define

The mechanism is a directory convention plus a manifest. The smallest useful plugin, per the README, is a directory containing plugin.json and a skills/ subtree, with each skill in its own folder holding a SKILL.md file. The manifest in the README's example carries two keys: $schema, pointing at https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, and name, set to the plugin name. The SKILL.md carries YAML front matter with name and description, followed by the instruction body. That is the whole data flow described in the introduction: a client reads plugin.json, then discovers skills/greet/SKILL.md. There is no registry, no install step, and no runtime contract in the README. The specification is what turns this from a convention into a contract, and the schemas directory holds the machine-readable form of that contract for both 1.0.0 and the 1.1.0 draft. The topics list names agent-skills and mcp alongside agent-plugins, which matches the stated scope of packaging both component types under one format.

The boundary the spec draws around client behaviour

The most consequential line in the README is the one that says how a client exposes the skill to users or models is outside the Agent Plugins specification. That is a deliberate scope cut, and it is the right one for a packaging standard, but it has teeth. Two conforming clients can load the same plugin and behave completely differently: one may inject the skill description into a system prompt, another may require the user to invoke it by name, a third may surface it only in a picker. Nothing in the package format constrains that. The same applies to MCP servers. The README states that the format is portable for them, but the introduction does not describe how a server is declared in plugin.json, how it is started, or what transport is expected. Those details would live in the versioned specification rather than the introduction. If you are evaluating this to decide whether a plugin will behave identically across hosts, the answer from the README alone is no, and you need to read spec/1.0.0.md before assuming otherwise.

Two published versions and the cost of tracking them

The repository ships 1.0.0 as the current published release and 1.1.0 as a working draft, with separate spec files and separate schema directories for each. That parallel layout is the maintenance story in miniature. A plugin author who pins $schema to the 1.0.0 URL gets a stable target; a client that wants to accept 1.1.0 plugins has to implement against a draft whose schema can still change. The repository has no retrieved releases, so version tracking happens through the spec files and schema directories rather than through tagged artifacts. Practically, that means upgrade cost is not a package-manager concern. There is nothing to bump in a lockfile. The cost is rereading spec/1.1.0.md against your implementation whenever the draft moves, and deciding when to migrate the $schema string in every plugin you publish. For a small plugin set that is an afternoon. For a client that validates incoming manifests against a schema, it is a code change plus a compatibility window where both versions must be accepted.

Licence status and what NOASSERTION leaves open

The repository metadata reports NOASSERTION for the licence, which means the licence could not be identified automatically and no standard identifier was applied. For a specification, that matters more than it would for an application. The text of the spec, the JSON schemas, and any example plugins are all things a vendor may want to copy into their own documentation or reimplement. Without a declared licence, the permission to do that is unclear. There is a Technical Charter in GOVERNANCE.md, and governance documents sometimes address licensing, so that file is the first place to look. Nothing in the supplied material states the licence terms, so treat this as unresolved rather than as permissive. If you are embedding the schemas in a commercial product, resolve the licence question before you build on them. This is a factual gap, not legal advice.

Where a single-vendor skill format is the better choice

The alternative to Agent Plugins is not a competing standard; it is the native extension format of the client you actually target. If you ship skills to exactly one agent host, that host's own directory layout and manifest give you more than Agent Plugins can, because the host can specify execution semantics, permission prompts, and tool wiring that a vendor-neutral packaging spec deliberately leaves out. The difference in approach is the point. A native format is a runtime contract: it can tell the host how to run the thing. Agent Plugins is a distribution contract: it tells any host where to find the thing. Adopting it buys you a second target without rewriting the package, and costs you the ability to express anything host-specific in the manifest. That trade is worth taking when you have two or more clients in scope and worth skipping when you have one, because you will end up maintaining a plugin.json alongside the native format anyway and gaining nothing from the extra file.

Who should adopt it and what to check first

Adopt Agent Plugins 1.0.0 if you maintain skills or MCP servers that need to reach more than one agent client and you want one directory layout instead of one per vendor. The layout is small enough to hand-write: a plugin.json with $schema and name, plus skills/<skill-name>/SKILL.md with name and description in the front matter. Do not adopt it if you need the package format to guarantee how a skill is presented or invoked, because the README states plainly that this is outside the specification. Do not adopt it yet if you depend on manifest keys that only appear in the 1.1.0 draft, since that version is still a working draft and its schemas live in a separate directory that can change. Before you commit, read spec/1.0.0.md and the files under schemas/1.0.0/ rather than the README, confirm that each client you care about already reads plugin.json, and check GOVERNANCE.md for the licence terms that the repository metadata leaves as NOASSERTION. If a target client does not read plugin.json today, the package format buys you nothing until it does, and that is the fact that decides the question.

Editorial conclusion

Adopt Agent Plugins 1.0.0 if you already ship skills or MCP servers to more than one agent client and want one directory layout instead of one per vendor. Do not adopt it if you need the spec to guarantee execution behaviour, because it explicitly leaves skill exposure to the client. Before committing, read spec/1.0.0.md and the schemas/1.0.0/ files directly rather than the README, confirm which of your target clients already read plugin.json, and check whether the 1.1.0 draft changes the manifest keys you depend on.

Official sources

1. agentplugins/agent-plugins-spec on GitHub
2. Issues
3. Project website
4. README