# Agent Plugins: a package format whose smallest example carries no version

> Agent Plugins is a vendor-neutral standard for packaging agent skills and MCP servers, currently at specification 1.0.0 with a 1.1.0 draft beside it. The substance is small and worth reading closely, because the boundary it draws is precise: a portable directory layout, and an explicit statement that everything past the package is somebody else's problem.

**agentplugins/agent-plugins-spec** — Agent Plugins Specification v1.0.0 — A minimal standard for packaging agent extensions into distributable plugins

- Repository: https://github.com/agentplugins/agent-plugins-spec
- Website: https://agent-plugins.org
- Stars: 1,347 · Forks: 75
- Language: Unknown
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/agentplugins-agent-plugins-spec

## The README states that it is not the contract

The first substantive line of the file is a disclaimer about the file itself. It calls itself a non-normative introduction and points at the versioned specification as the thing that defines the portable contract. That single sentence does most of the work in the whole repository, because it establishes that nothing in the quick start, including the example directory layout and the example plugin.json, is binding. The authority lives in spec/1.0.0.md and in the schemas directory beside it.

This is worth pausing on, because it is unusual for a project README to disclaim itself in the second paragraph. Most format proposals spend their opening on what the format does, and leave the question of what is enforceable until a governance section much further down. Here the sequence is inverted: status first, then a quick start that is explicitly illustrative, then the document index. The status block itself is two lines long, naming specification 1.0.0 as the current published release and 1.1.0 as a working draft. Nothing in the file promises a schedule for the draft, a compatibility promise between the two versions, or a process for moving a package from one to the other.

## The smallest useful plugin declares no version

The quick start builds a plugin from two files. The layout is a directory named for the plugin, a plugin.json at its root, and a skills directory holding one skill folder with a SKILL.md inside it:

```text
hello-plugin/
├── plugin.json
└── skills/
    └── greet/
        └── SKILL.md
```

The manifest carries two keys and nothing else:

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}
```

A name and a schema pointer. There is no version field, no format identifier, no publisher, no entry point list and no dependency declaration. The only thing in this example that ties the package to a version of the specification is the path inside the $schema URL, which ends in schemas/1.0.0/. So a consumer reading plugin.json alone cannot determine which contract the package was written against, and cannot tell whether a package validated against the 1.0.0 schema would also validate against the 1.1.0 one. For a standard whose entire purpose is portability between clients, the identity of the contract is inferred from a URL rather than declared in the document.

## Two schema trees ship at once, one published and one draft

The project document index pairs each specification version with its own schema directory. Specification 1.0.0 links to schemas/1.0.0/, and the working draft 1.1.0 links to schemas/1.1.0/. Both trees are in the repository now, and the status block labels only the first as published.

That arrangement is normal for a standards effort and creates a specific hazard for anyone writing tooling. A validator that resolves a schema by version needs a rule for which version to ask for, and this repository offers two candidate answers sitting in the same tree with different maturity. A client that resolves the draft schemas and a client that resolves the published ones are reading different contracts while both appearing correct. Nothing in the index marks one as deprecated, and nothing indicates whether the draft schema directory is expected to change shape, which matters because tooling built against a draft schema would need rebuilding when the draft settles. The plugin.json example sidesteps the question by pointing at the published path, which is a helpful default and also an implicit argument that the published tree is the one to target.

## Validation and version discovery both require the network

The $schema value in the manifest is an absolute URL under the project's own domain:

```
https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
```

It points at agent-plugins.org rather than at a relative path inside the package, which is a choice with consequences worth naming. An editor or validator that dereferences $schema over HTTP will reach out to a remote host to check a two-key document, and an offline or air-gapped machine will not get an answer. The same applies to tooling that wants to discover which specification version a package targets, since the version is only present inside that remote path.

A relative reference such as a schemas directory shipped alongside the manifest would answer the same questions with no network call and no dependency on the project's site staying up and serving the same bytes. The chosen form does have a virtue: the URL pins an exact specification version in a way a relative path would not, and a publisher can point a package at a different version by changing one string. So this is a trade rather than a mistake, and the cost lands on whoever writes the validator, which is precisely the audience this standard is trying to serve.

## The scope stops exactly at the package boundary

One sentence defines where the standard ends. After explaining that a client supporting skills can load a plugin by reading plugin.json and discovering the SKILL.md file, the file says how the client exposes the skill to users or models is outside the Agent Plugins specification.

That is the whole boundary, and it is drawn at a defensible place. Everything about layout, naming and file discovery is portable and gets standardised. Everything about the user experience, the prompt surface, the tool list a model sees and the permission model belongs to the client. It also means the term plugin here is narrow: it names a distributable directory, not an installed capability with defined behaviour, and a client that loads the directory correctly may still present the contents in a way the publisher never sees or cannot influence.

The practical consequence for anyone writing a loader is that the discovery step is fully specified while the exposure step is entirely yours, so two clients can both be conformant and behave nothing alike. That is a reasonable division, and it is also the division that makes conformance testing cheap: there is a manifest to read and a file to find, and everything after that belongs to the implementation.

## The format covers MCP servers, and the quick start shows none

The opening description gives the scope as a portable package format for Agent Skills and MCP servers. Two kinds of payload, then. What the quick start builds is the first kind, a single skill folder with a SKILL.md carrying YAML front matter and a body:

```markdown
---
name: greet
description: Greet the user and offer help.
---

Greet the user and offer help.
```

The front matter holds a name and a description, and the body repeats the description as prose. No MCP server appears anywhere in the introduction, and no example directory shows what an MCP payload looks like inside this package layout, whether it needs a different key in plugin.json, or how a client distinguishes the two kinds. The document index points at the specification for those answers.

So the readable surface of the project teaches one of the two payload types and defers the other. That is a reasonable division of labour between an introduction and a specification, and it is worth knowing before you start, because MCP is the part most implementers would want and the part the quick start leaves entirely unillustrated.

## Governance is four documents, and the licence files do not line up with the metadata

The root of the repository is mostly documentation. Alongside the README there is a GOVERNANCE.md linked from the index as the technical charter, a MAINTAINERS.md, a CONTRIBUTING.md, an AGENTS.md, and a FUTURE_CONSIDERATIONS.md linked as future considerations. Two specification files and two schema directories complete the tree.

For a project whose entire output is a specification, that is a heavy governance investment, and a specific one: a charter, a named maintainer list, a contributions process and a document for things deliberately left out of scope. The future considerations file in particular is the one most specifications do not publish, since naming what a standard will not address is as informative as naming what it will.

The licence is where the file list and the recorded licence disagree. The root carries LICENSE.md and a LICENSES directory, both of which read as licensing artefacts, while the licence recorded against the repository is empty. Those cannot both be the whole story, and the two sources do not settle which text governs, or what the LICENSES directory holds. For a document set intended to be built on by others, that ambiguity is the one item here with legal weight rather than technical weight, and it is resolvable by reading the files.

## Conclusion

Agent Plugins is worth reading if you are designing a plugin format of your own and want to see where the line between portable and non-portable gets drawn, because the spec puts that line in an unusual place: everything inside the directory is standardised, everything about how a client surfaces a skill is explicitly left out. Two things to settle before adopting it. First, the minimal plugin.json shown in the quick start declares no version at all, so a consumer cannot tell 1.0.0 from 1.1.0 by reading the package, and the only version signal in that example is the $schema URL pointing at agent-plugins.org, which means validation and version discovery both require the network. Second, two schema trees ship side by side, one published and one a working draft, so a tool that resolves the published schemas is not reading the same contract as one that resolves the draft. The repository has no GitHub releases, so the specification is versioned in filenames rather than in tags, and the licence situation needs reading directly: the file list carries LICENSE.md and a LICENSES directory while no licence is recorded for the repository itself, and until those agree you should not assume terms for a format you intend to build on. The governance side is unusually complete for a document set this size, with a technical charter, a maintainers file, a contributions guide and a future considerations document all committed at the root.

## FAQ

### What does the Agent Plugins specification standardise?

It defines a portable package format for Agent Skills and MCP servers, so both can be distributed as plugins. It covers the directory layout, the plugin.json manifest and the discovery of skill files, and it places how a client exposes a skill to users or models outside the specification.

### What goes in plugin.json for an Agent Plugins package?

The smallest useful example carries two keys: a name and a $schema pointer to the schema hosted at agent-plugins.org for the version being targeted. That example declares no version field of its own, no publisher and no dependency list, so the specification version appears only inside the schema URL.

### Is the Agent Plugins specification 1.1.0 finished?

No. Version 1.0.0 is named as the current published release and version 1.1.0 as a working draft. Both ship in the repository with their own schema directories, and the draft carries no schedule or compatibility statement in the project documents.

### How do I get the Agent Plugins specification?

It is a document set rather than an installable package, so there is nothing to install. The specification text is in spec/1.0.0.md, the machine-readable schemas are under schemas/1.0.0/, the draft version sits beside them, and the site at agent-plugins.org serves the schema files referenced by the manifests.

### Does an Agent Plugins package declare which specification version it targets?

Not in the manifest itself. The minimal plugin.json example has a name and a $schema URL, and the version appears only as a path segment inside that URL, which points at schemas/1.0.0/. A consumer reading the manifest alone cannot tell which contract the package was written against.

## Sources

- [agentplugins/agent-plugins-spec on GitHub](https://github.com/agentplugins/agent-plugins-spec)
- [Issues](https://github.com/agentplugins/agent-plugins-spec/issues)
- [Project website](https://agent-plugins.org)
- [README](https://github.com/agentplugins/agent-plugins-spec/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agentplugins-agent-plugins-spec