Agent Plugins: Package Skills and MCP Servers Once

Concept 1: The Problem Agent Plugins Solves

Before understanding the solution, understand the pain point.

The situation before Agent Plugins:

• AI agents can be extended with two things:
  • Agent Skills → reusable instructions/resources for agents
  • MCP servers → tools and services agents can connect to
• These extensions already existed, but each client (ChatGPT, Cursor, VS Code, etc.) expected them packaged differently
• Same underlying component, repackaged multiple times just to satisfy different clients

Think of it like this:

Imagine writing one great song, but every music platform requires a completely different file format. You'd have to re-record it for each one — even though the song itself never changes.

Agent Plugins fixes this by giving extensions ONE standard package format that all compatible clients understand.

---

Concept 2: What the Standard Package Looks Like

Agent Plugins defines a directory structure — a predictable "home" for your components.

my-plugin/
├── plugin.json          ← The manifest (required)
├── skills/              ← Agent Skills live here
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json             ← MCP server config lives here
└── com.example.client/  ← Client-specific extras (namespaced)

Breaking this down:

The minimal plugin.json looks like this:

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

Just two fields. That's the minimum requirement. The rest of the contract lives in the file structure itself.

---

Concept 3: How Clients Read the Package

Every compatible client follows the same discovery process:

Step 1: Check for plugin.json at the root → validates the plugin exists
Step 2: Look under skills/ → if client supports Skills, load them
Step 3: Read mcp.json → if client supports MCP servers, load them
Step 4: Validate each component independently

Key insight — independent validation:

If one component is broken or invalid, the other components still work. A bad mcp.json doesn't disable your Skills, and vice versa.

A client doesn't need to support both component types. It can support:

• Only Skills ✓
• Only MCP servers ✓
• Both ✓

---

Concept 4: Why It's Intentionally Small ("Small on Purpose")

Agent Plugins deliberately covers only two component types:

1. Agent Skills
2. MCP servers

Why not include everything?

Because both of these already had:

• Their own existing specifications
• Meaningful adoption in the ecosystem

Agent Plugins doesn't redefine them — it only defines how clients find them together in one distributable package.

What's left OUT intentionally:

• Commands
• Hooks
• Agents
• Installation behavior
• Distribution mechanisms
• User experience decisions

Think of Agent Plugins as defining the shipping container standard, not what goes inside each box or how the truck delivers it.

The benefit of staying small:

• Easier to implement for client builders
• Gives the ecosystem room to evolve before locking in more standards
• Faster adoption across vendors

---

Concept 5: The Namespaced Extension Mechanism

Clients need freedom to innovate. Agent Plugins handles this with namespaced extensions.

How it works:

my-plugin/
└── com.example.client/   ← This is a client-specific namespace

• Each client defines its own namespace (like com.cursor.client/)
• Other clients completely ignore namespaced folders they don't own
• Client-specific behavior stays outside the portable contract

Why this matters:

Without namespacing:
Client A adds custom feature → bleeds into the standard → blocks Client B's adoption

With namespacing:
Client A adds custom feature → stays in its own namespace → Client B ignores it → standard stays clean

A client-specific capability stays client-specific until there's consensus to standardize it. This prevents premature standardization.

---

Concept 6: The Multi-Vendor, Open Governance Model

Agent Plugins isn't owned by one company. This is important for trust and adoption.

Who built it:

• Initiated by Vercel
• Refined collaboratively by: AWS, Anysphere, GitHub, Microsoft, OpenAI, and Vercel

Technical Steering Committee includes:

• AWS, Cursor, Microsoft, OpenAI, Vercel

What "open" means here:

• Openly licensed
• Public maintainers, contribution process, and technical decisions
• No single company's roadmap controls the direction

This is the same model that made standards like HTML and HTTP successful — no single gatekeeper.

---

Concept 7: The Value Proposition — Putting It All Together

For plugin authors:

Before: Package Skills for Client A → Repackage for Client B → Repackage for Client C
After:  Package once → Works across all compatible clients automatically

For client builders:

Before: Define your own discovery format, hope authors support it
After:  Follow the conformance checklist → automatically support all Agent Plugins

Clients supporting Agent Plugins at launch:

• ChatGPT and Codex
• Cursor
• GitHub Copilot
• Kiro
• VS Code

---

Summary: The Core Mental Model

Agent Plugins = A shipping container standard for AI agent extensions

┌─────────────────────────────────────────┐
│              plugin.json                │  ← Manifest (required)
│         (2 fields minimum)              │
├──────────────────┬──────────────────────┤
│    skills/       │     mcp.json         │  ← Portable components
│  (Agent Skills)  │   (MCP servers)      │
├──────────────────┴──────────────────────┤
│         com.client.namespace/           │  ← Client-specific (ignored by others)
└─────────────────────────────────────────┘

One package → Many compatible clients

The three-word contract: Package once, run anywhere.