Agent Plugins Explained: Skills and MCP in One Folder

Introduction

On August 6, 2026, Agent Plugins 1.0.0 was published: an open, vendor-neutral standard for packaging Agent Skills and MCP servers into a single portable directory. Vercel proposed it. Amazon, Anysphere (Cursor), GitHub, Microsoft, and OpenAI refined it. Google announced the same day that it was joining as a core maintainer and shipping plugin support in its own products.

Here is the surprising part: almost none of it is new.

Agent Plugins does not invent a skill format. It does not invent a tool protocol. It defines a manifest with two required fields, then points at two specifications that already existed and already had cross-client adoption. The entire standard is a wrapper.

That restraint is the reason to pay attention. Most "new standard" announcements ask you to learn a new format. This one asks you to put things you may already have into two folders with fixed names.

If you have read our guides on building an Agent Skill from scratch and building an MCP server, you already know both halves of a plugin. This article covers the wrapper around them.

What you'll learn:

• What a plugin actually is on disk, field by field
• Why building on existing standards is the design decision that matters
• The failure-isolation rule worth stealing for your own systems
• What v1 deliberately leaves out, and why that is a feature
• Which clients support it today, and where Claude Code sits
• Whether packaging one is worth your time today

What Agent Plugins Actually Is

A plugin is a directory. That is the whole idea.

my-plugin/
├── plugin.json          # Required manifest
├── skills/              # Optional: Agent Skills
│   └── summarize/
│       └── SKILL.md
├── mcp.json             # Optional: MCP server declarations
└── com.example.client/  # Optional: client-specific extensions

The problem it solves is one that plugin authors have been quietly absorbing for a year. Every client grew its own packaging format, even when the things being packaged were identical. The same skill and the same MCP server had to be repackaged per client, each with a different manifest name, directory layout, and configuration shape.

The spec authors call the result fork and drift. You publish for one client, someone forks it for another, and the two copies diverge. Authors faced a choice between reaching every client and using what made each client valuable.

Agent Plugins removes the packaging decision from that equation. One directory, loadable by any conformant client.

Why Almost None of It Is New

The two component types were deliberate choices, not an arbitrary starting set.

Agent Skills are folders containing a SKILL.md with YAML frontmatter and Markdown instructions. Two required fields, name and description, and a body the agent loads on demand.

MCP connects agents to tools and data over a defined wire protocol, now stewarded by the Linux Foundation. Our MCP v2 guide covers where the protocol itself is heading.

The specification is explicit that this pairing is the point. v1 focuses on these two because both have "established specifications outside this project and meaningful cross-client adoption." Other candidate component types, commands, hooks, agents, and LSP servers, are named and excluded because their formats have not converged yet.

This is a standard that waited for consensus instead of manufacturing it. Note also the division of labor: Agent Plugins defines the mcp.json configuration file, while the MCP specification still owns the wire protocol. The new standard claims only the packaging layer.

Anatomy of a Plugin

plugin.json: two required fields

The manifest is deliberately thin. Only $schema and name are required.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "deploy-toolkit",
  "version": "1.2.0",
  "description": "Deployment runbook and its tool integration",
  "author": { "name": "Your Team", "url": "https://example.com" },
  "license": "MIT",
  "keywords": ["deployment", "ci"]
}

name must be 1 to 64 characters, lowercase alphanumeric with hyphens and periods, and cannot start or end with a symbol or contain -- or ... Everything beyond $schema and name is optional metadata: version, description, author, homepage, repository, license, keywords, and extensions.

The schema is closed, meaning no fields beyond those are permitted. But there is a smart exception: a client encountering an unknown top-level field must report and ignore it, then keep loading the plugin. Strict validation, forgiving failure.

skills/: a fixed location, not a new format

Skills live in skills/, and that location is not configurable. Each immediate child directory containing a file named exactly SKILL.md is treated as one skill.

That is the entire integration. Your existing skills, unchanged, moved into a folder with a fixed name. They still follow the Agent Skills specification, including the scripts/, references/, and assets/ conventions.

The rigidity is intentional. The spec offers no flexibility in where components live and no inline declarations, because every configurable path is a place where two clients could disagree.

mcp.json: transports, and the two placeholders

MCP servers are declared in a separate mcp.json at the plugin root, never inline in the manifest.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${PLUGIN_ROOT}/server/index.js"],
      "env": { "CACHE_DIR": "${PLUGIN_DATA}/cache" }
    },
    "remote-api": {
      "type": "streamable-http",
      "url": "https://api.example.com/mcp"
    }
  }
}

Three transports are defined: stdio, streamable-http, and sse (the legacy transport). Transport is always declared explicitly, with no negotiation and no fallback. A client supporting MCP must support at least one of stdio or streamable-http; sse support is optional.

Two placeholders exist, and only two:

• ${PLUGIN_ROOT} resolves to the plugin's own directory.
• ${PLUGIN_DATA} resolves to a client-managed writable directory that survives plugin updates.

PLUGIN_DATA is the more interesting one. It is where installed dependencies, node_modules, virtual environments, generated code, and caches belong. Without it, every plugin update would blow away installed state, and each client would invent its own answer.

Expansion is narrow by design: a single, non-recursive textual replacement, applied only to MCP args, env values, and cwd. Clients must not perform any other placeholder or environment-variable expansion. One caveat worth internalizing: values in env are visible package data, not a secrets mechanism. Do not put credentials there.

Paths are also contained. Plugin-relative paths must begin with ./ and must resolve inside the plugin root. A "../bin/server" that escapes the root is rejected outright.

Client extensions: the escape hatch that keeps the core small

Clients still have features the portable core does not cover. Rather than growing the spec, Agent Plugins gives them namespaced space using reverse-domain naming, in the manifest:

{
  "extensions": {
    "com.example.client": { "autoActivate": true }
  }
}

and as a top-level directory:

my-plugin/
└── com.example.client/
    └── hooks/
        └── hooks.json

Clients must ignore namespaces they do not implement, without validating the contents. The spec assigns no portable meaning to anything inside these directories.

This is what lets the core stay small. Vendor-specific capabilities such as custom agents, commands, rules, and hooks get a home that does not require a spec revision, and the portable surface stays genuinely portable.

The Design Decision Worth Stealing

The best engineering idea in this specification has nothing to do with plugins.

Agent Plugins draws a hard line between failures that kill the package and failures that kill one component:

Fatal, meaning the whole plugin is rejected:

• plugin.json is not valid JSON
• $schema or name is missing, or name breaks the naming rules
• Any path in the package resolves outside the plugin root

Non-fatal, meaning skip that piece and keep going:

• A skill violates the Agent Skills spec, so that skill is skipped
• An MCP server entry is malformed, declares an unknown transport, or fails to connect
• The client does not support the declared transport
• An unknown top-level manifest field appears

The governing rule is stated plainly: a failure isolated to a component type, entry, or process must not prevent the client from loading independently valid components.

The practical payoff is real. If your plugin ships a skill plus an MCP server, and the MCP server's remote endpoint is down or the user never configured its credentials, the skill still works. The plugin degrades instead of disappearing.

Anyone who has watched one bad entry take down an entire config file knows why this matters. It is a good default for any plugin system you design.

What v1 Deliberately Leaves Out

The non-goals are as informative as the spec itself. v1 does not define archive formats (plugins are directories, not .zip files), registries or package managers, credential and OAuth configuration, sandboxing, a trust or permission model, provenance verification, plugin-to-plugin dependencies, auto-update mechanisms, or a test harness. The companion FUTURE_CONSIDERATIONS.md lists each as deferred rather than dismissed.

What that means in practice: portability stops at packaging. Discovery, installation, permissions, and trust remain per-client. A plugin format is not a marketplace, and it is not a security boundary. Installing a third-party plugin still means running third-party code with whatever privileges your client grants it.

Who Supports It Today

The spec is governed by a technical steering committee of Amazon, Anysphere (Cursor), Microsoft, OpenAI, and Vercel, with Google joining as a core maintainer on launch day. Notably absent is Anthropic, which created both of the standards being packaged.

At launch, Vercel listed ChatGPT and Codex, Cursor, GitHub Copilot, Kiro, and VS Code. On August 12, GitHub shipped support in VS Code, Copilot CLI, the Copilot SDK, and the Copilot app, installable through the Awesome Copilot marketplace.

Claude Code is not among them, and it already ships its own plugin format: the manifest lives at .claude-plugin/plugin.json, with commands/, agents/, skills/, hooks/, and .mcp.json alongside it. Same word, different structure, not currently compatible. If you want to reach Claude Code plus the launch clients today, plan on two manifests. The expensive parts, the SKILL.md files and the MCP server itself, are shared. Only the wrapper differs.

Should You Package One Yet?

It depends on what you already have.

If you maintain a skill or MCP server that people install today, yes. The migration cost is close to zero. Add a plugin.json with two required fields, move existing skills into skills/, and declare servers in mcp.json. You are not rewriting anything. You are renaming directories.

If you are shipping a skill and a server that belong together, this is the strongest case. Bundling was the actual gap. A deployment runbook and the tool integration it depends on could not previously travel as one unit, and users had to install two things and hope the versions matched.

If you are building for one client and have no distribution plans, not yet. The standard's value is portability. Without a second target, you are adopting a manifest for its own sake, and your client's native format probably exposes more of what makes it useful.

If you need permissions, sandboxing, provenance, or secret management, wait. v1 explicitly does not cover those, and building around gaps the spec plans to fill is how you end up migrating twice.

The honest summary: Agent Plugins is not a leap forward in capability. It is a modest, well-scoped agreement that removes a repetitive packaging tax. Standards that succeed usually look like this, boring, narrow, and mostly made of parts that already worked.

We will follow up with a hands-on guide that builds and ships a real plugin end to end, once the client ecosystem settles enough for the walkthrough to stay accurate.

Resources

• Agent Plugins Specification — the full normative v1.0.0 contract
• Agent Plugins homepage — author and client implementation guides
• JSON Schemas — the canonical manifest schema
• Future Considerations — what v1 defers and why
• Agent Skills Specification — the SKILL.md format
• Introducing Agent Plugins 1.0.0 — Vercel's launch announcement
• Agent Plugins 1.0 in VS Code and Copilot — GitHub's rollout
• Agent plugins: package your skills, tools, and more — Google's announcement

Related Articles

• How to Build and Deploy an Agent Skill from Scratch — build the skill half of a plugin
• Top AI Agent Standards to Know in 2026 — AGENTS.md, SKILL.md, and DESIGN.md in context
• MCP v2: What's Changing, What's Deprecated, and Why — where the protocol half is heading
• Build an MCP v2 Server in TypeScript — build the MCP half of a plugin
• Top 5 AI Agent Protocols to Know in 2026 — how MCP fits among agent protocols