One Plugin, Every Agent: Why the Agent Plugins Spec Matters

Six plugins. One feature. That math never made sense.

Constellation ships a plugin for Claude Code. And one for Codex. And Copilot, Cursor, Antigravity, and OpenCode. Every one of them delivers the same thing: our MCP server plus a handful of skills that teach the agent when to reach for code intelligence. Six repositories, six manifest formats, six sets of installation docs, six release pipelines. The content is identical. The packaging never was.

So when the Agent Plugins specification hit 1.0.0, an open, vendor-neutral standard for packaging exactly this kind of thing, we didn't just take notice. We celebrated. This post is about why the spec matters, what it actually standardizes, where it still has gaps, and what we built with it.

The Fragmentation Tax

Back in April we broke down the extension primitives that AI coding tools expose: instructions, skills, rules, commands, and hooks, and how plugins bundle them into shareable packages. We closed that post with an observation: the concepts were converging across the ecosystem, but the terminology and file layouts were not. Every client had invented its own dialect.

That divergence is not an abstract concern for us. It's a line item.

A skill is a markdown file with frontmatter. It is the most portable artifact imaginable. And yet, to deliver the same markdown file to six agent clients, we maintained six repositories with six different directory conventions, six manifest schemas, and six answers to the question "where does the MCP server config go?" When we improved a skill, we propagated the change six times. When a client changed its plugin format, we chased it.

We were not alone. Every team publishing agent extensions paid the same tax, and every client that launched a plugin system added a new column to the spreadsheet. The ecosystem was rediscovering a very old lesson: when every platform invents its own package format, authors become porters.

What the Spec Actually Standardizes

The Agent Plugins specification takes a refreshingly modest approach. In its own words, it defines "a small interoperability floor for the parts that can be portable across clients." It does not try to standardize how clients surface plugins to users, how they're distributed or installed, or how permissions work. Those stay under each client's control, where they belong.

What it does standardize is the package itself:

• plugin.json, a manifest at the plugin root that identifies the plugin and the spec version it targets. The schema is deliberately closed: a name, optional metadata like version, description, author, and license, and nothing else.
• skills/, a directory where each child folder containing a SKILL.md is one skill. The skill format itself is governed by the Agent Skills specification, which the plugin spec simply points at rather than reinventing.
• mcp.json, a configuration file for Model Context Protocol servers, supporting stdio, streamable HTTP, and legacy SSE transports, with plugin-relative paths and placeholders like ${PLUGIN_ROOT} so packages stay relocatable.
• Reverse-domain extension namespaces, an escape hatch for client-specific data. A client can stash its own configuration under a key like com.example.client without breaking portability, and every other client just ignores it.

That's the whole surface. Two component types, one manifest, one predictable directory structure. A conformant client can walk any conformant plugin and know exactly what it will find:

The portable core (blue) is what every client reads the same way. The extension namespaces (dashed) carry client-specific data without breaking the package for anyone else.

If that sounds small, that's the point. The history of successful interoperability standards is a history of small, boring cores with room to grow. The spec resisted the temptation to boil the ocean, and the result is something every client can actually implement.

Why the Governance Gives Us Hope

A specification is only as good as the coalition behind it, and this is where we went from interested to genuinely optimistic.

The Technical Steering Committee includes core maintainers from Amazon, Cursor, Microsoft, OpenAI, and Vercel. Read that list again. These are competing platforms, several of which built the very bespoke plugin systems this spec consolidates, agreeing on a common package format. Feature proposals start in public GitHub Discussions, portability requirements get debated in the open, and the spec only adopts what implementers actually commit to. The whole thing is openly licensed and developed in public.

We want to say this plainly, because it's the reason this post exists: thank you. Standardization work is thankless, slow, and full of meetings. Nobody ships a flashy demo of a JSON schema. The maintainers who sat down, set aside their own formats' quirks, and negotiated a common floor did the unglamorous work that ecosystems are built on. Package authors everywhere are the beneficiaries.

We've seen this movie before, and it ends well. LSP meant language tooling authors stopped writing one integration per editor. MCP meant tool builders stopped writing one integration per agent. Agent Plugins extends the same logic to the knowledge layer: write your skills once, configure your server once, and let any conformant client load the result.

What the Spec Leaves Out (For Now)

Celebration doesn't require pretending the floor is a ceiling. Version 1.0.0 is explicit about its limits: "Agent Plugins v1 defines exactly two component types: skills and MCP servers. Other component types are outside the v1 format."

Measured against the full set of primitives the richest clients support today, that leaves real gaps:

• Hooks. Claude Code plugins can ship event-driven scripts that run before or after tool calls, the system-level immune system we wrote about in April. The spec has no portable equivalent, and hooks are arguably the hardest primitive to standardize: they execute arbitrary code at privileged moments, so a portable format needs a permission story first.
• Commands. Slash-command workflows, the /work-ticket style orchestration that encodes how work gets done on a team, remain client-specific.
• Rules and agents. Scoped guardrails and custom subagent definitions have no portable home either.

Today, all of these live in the reverse-domain extension namespaces, which is an honest way of saying "not portable yet." A plugin that leans on hooks or commands is still, in practice, a plugin for one client.

The roadmap suggests the gaps are understood. The project's future-considerations document sketches permission declarations, signature verification, secrets handling, and enterprise policy controls, exactly the trust infrastructure that riskier primitives like hooks would need before they could ever be portable. Skills and MCP servers went first because they're declarative and safe to load anywhere. The sharper tools will take longer, and given the stakes, they should.

We'd rather have a small spec that's actually implemented than a sprawling one that isn't. But we'll be in the Discussions advocating for the rest of the primitives, hooks especially, because the fragmentation tax on them is still being collected.

Our First Agent Plugin

We didn't just want to applaud from the audience. constellation-agent-plugin is Constellation packaged as a spec-conformant Agent Plugin, targeting version 1.0.0: our MCP server exposing the code_intel tool, plus six skills covering impact analysis, dependency analysis, dead code detection, architecture overviews, health checks, and troubleshooting.

One repository. One manifest. One skills/ directory. Any client that implements the specification can load it, including clients that don't exist yet. Our six bespoke plugins aren't going anywhere while the ecosystem transitions, but every skill improvement now has a canonical home, and the portable package is the one we'll grow first.

One friendly note before you install anything: if we ship a native plugin for your tool, use that one. The gaps we described above are exactly why. Our Claude Code, Codex, Copilot, Cursor, Antigravity, and OpenCode plugins take full advantage of each client's bespoke capabilities, the hooks, commands, and rules the portable format can't carry yet, and that adds up to a noticeably better Constellation experience. The Agent Plugin is the right choice when your client has no native plugin, and it's where everything converges once the spec reaches parity. Until then, native first.

That's the quiet promise of a good standard: the seventh client costs us nothing.

Six formats going on one. We'll take that math.

---

At ShiftinBits we're building Constellation, the shared code intelligence layer for AI coding agents. Constellation maintains a team-wide knowledge graph of your codebase and exposes it to tools like Claude Code, Cursor, GitHub Copilot, and Windsurf via the Model Context Protocol (MCP), giving them structural understanding of your code with symbol-level search, dependency graphs, impact analysis, and more.

If you're building with AI coding tools and want to see what your agents can do with real code intelligence, check out Constellation. For a limited time, we're giving early adopters 50% off with the promo code ROOTNODE50.