Stacks and Flows

Packaging Boundary Guide · Source-verified

Agent Plugins 1.0: portable Skills + MCP — and where portability stops

Agent Plugins 1.0 defines a portable package for Agent Skills and MCP server configuration. It standardizes a small interoperability floor, not installation, permissions, distribution, UI, credentials, or every client extension.

Packaging boundary

Package the portable floor, name the client boundary

plugin.json
declare package
Agent Skills
bundle instructions
mcp.json
configure servers
Compatible client
install and enforce
Client policy + extensions
Agent Plugins standardizes a manifest plus Skills and MCP configuration. Installation, credentials, permissions, UX, and client extensions stay outside the portable core.

What the sources establish

  • The published 1.0.0 specification requires a plugin.json manifest and can package Agent Skills under skills/ plus MCP server configuration in mcp.json.
  • The portable v1 component set is limited to Agent Skills and MCP servers; commands, hooks, agents, rules, and LSP servers remain outside the portable core.
  • Client-specific data and files can use reverse-domain extension namespaces, but other clients may ignore them.
  • Installation, distribution, enablement, updates, permissions, credentials, and user experience remain client-controlled boundaries.

Why a packaging layer exists

Skills and MCP server settings can be individually portable yet still require different layouts in each client. Agent Plugins supplies a manifest and fixed component locations so compatible clients can discover the shared parts consistently.

Where portability stops

The v1 floor covers Skills and MCP configuration. Distribution, installation, permissions, credentials, UX, update policy, and client-specific commands or hooks remain outside that floor. A conformant package can therefore behave differently across clients without violating the specification.

Not MCP Apps or Skills over MCP

MCP Apps adds an interactive UI resource to a tool. SEP-2640 defines how a server can expose Skills over MCP. Agent Plugins packages local or distributable Skills and MCP connection definitions. The boundaries can complement each other, but they solve different problems.

Plugin or smaller unit?

Use a plugin when the package is the product boundary. Keep a standalone Skill or MCP server when it can be installed, versioned, secured, and understood independently; fewer layers reduce compatibility and credential-management work.

Decision detail

  1. Create a plugin when several reusable Skills and MCP connections need one inspectable package for multiple compatible clients.
  2. Publish a Skill alone when instructions and supporting files are the whole reusable unit.
  3. Publish an MCP server alone when the durable interface is a tool or data service and packaging adds no decision value.
  4. Before claiming portability, test the named clients, supported transports, environment variables, credential handling, extension namespaces, and update path.

Evidence

These claims are source-verified. We do not label this page hands-on or benchmarked because no reproducible test artifact is attached.

Continue the decision