Agent Plugins: One Portable Format for Skills and MCP Servers

Direct Answer

Agent Plugins is an open, vendor-neutral packaging standard for putting reusable Agent Skills and supported MCP server configurations into one directory that multiple agent products can discover. Version 1.0.0 defines a small portable core: a root plugin.json, optional skills under skills/, and optional MCP configuration in root mcp.json.

The important word is packaging. The standard does not make every agent runtime identical. It does not standardize marketplaces, installation, permissions, authentication, UI, billing, or process isolation. A conforming client can support skills, MCP servers, or both, and it can add its own capabilities without changing the portable core.

Watch the Official Announcement

Official launch: the announcement says contributors from AWS, Cursor, GitHub, Microsoft, OpenAI, and Vercel collaborated on the format. Read the official project site, the v1.0.0 specification, and the open specification repository. This article is an independent implementation guide based on those primary sources.

The Problem: Every Agent Expected Different Packaging

Skills and MCP servers were already becoming reusable building blocks, but the surrounding package was fragmented. Authors had to maintain different manifests, directories, path conventions, and setup instructions for each host. The capability might be the same while the integration code around it kept multiplying.

Agent Plugins creates an interoperability floor. Authors get one predictable place for portable identity, skills, and MCP configuration. Clients get one predictable discovery contract. The project does not attempt to freeze every product into the same feature set, which is why the initial specification is intentionally narrow.

What Version 1 Actually Standardizes

The normative page calls this Agent Plugins Specification v1.0.0 and currently labels its status Working Draft. Its portable component surface contains exactly two types:

1. Agent Skills. Reusable instructions and workflows that follow the separate Agent Skills specification.
2. MCP servers. Local or remote tool and data connections described by a portable mcp.json, while wire behavior follows the Model Context Protocol.

Commands, hooks, custom agents, rules, language servers, and UI are not portable v1 components because their formats have not converged. They can still exist as client extensions. That is a healthier boundary than pretending partially compatible features are universal.

The Portable Package Anatomy

my-plugin/
|-- plugin.json
|-- skills/
|   `-- summarize/
|       |-- SKILL.md
|       |-- scripts/
|       `-- references/
|-- mcp.json
|-- com.example.client/
|   `-- hooks/
|-- LICENSE
`-- CHANGELOG.md

Discovery uses fixed locations. The root manifest does not point to a custom skill directory or inline MCP configuration. Skills are discovered only from immediate child directories under skills/; clients do not recursively hunt for deeper SKILL.md files.

Build the Smallest Conforming Plugin

The official author guide starts with one manifest and one skill:

hello-plugin/
|-- plugin.json
`-- skills/
    `-- greet/
        `-- SKILL.md

plugin.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin",
  "version": "1.0.0",
  "description": "A portable greeting workflow",
  "license": "MIT"
}

skills/greet/SKILL.md:

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

Greet the user and offer help.

Only $schema and name are required in the v1 manifest. The schema is closed: permitted root fields are $schema, name, version, description, author, homepage, repository, license, keywords, and extensions. Component paths do not belong in this file because discovery locations are fixed.

Add a Portable MCP Server

Add mcp.json only when the plugin needs tools or live data. This example shows one bundled local server and one remote Streamable HTTP endpoint:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp",
      "headers": {
        "X-Tenant": "public-tenant"
      }
    }
  }
}

A stdio command is one executable token, not a shell command string. A bundled executable uses a ./ path inside the package. ${PLUGIN_ROOT} points at installed package files; ${PLUGIN_DATA} points at client-managed persistent writable storage. Placeholder expansion is supported in args, env values, and cwd, not in command, URLs, or HTTP headers.

Portable Does Not Mean Identical

The official compatibility page currently lists ChatGPT and Codex, Cursor, GitHub Copilot, Kiro, and VS Code. All list Agent Skills support. The MCP transport matrix differs:

This matrix is a point-in-time implementation claim, not a guarantee that every workflow behaves the same. Validate installation, skill discovery, tool exposure, authentication, approvals, failure reporting, and uninstall behavior in every client you promise to support.

Do Not Confuse the Portable and Client Package Layers

OpenAI's current plugin authoring documentation describes a richer ChatGPT and Codex package whose required entry point is .codex-plugin/plugin.json. That manifest can point to skills, bundled MCP configuration, registered MCP mappings, hooks, assets, and install-surface metadata. The Agent Plugins specification, by contrast, requires a portable plugin.json at the package root and discovers skills/ and mcp.json from fixed locations.

These layers can coexist during migration. The shared root expresses the portable minimum; client-specific files preserve richer features and distribution metadata. Do not delete a working client manifest merely because you added the new root manifest. The canonical Agent Plugins example repository recommends an additive migration and compatibility testing before legacy files are removed.

What the Standard Secures, and What It Does Not

A safe client should still display provenance, inspect executables and scripts, request least-privilege permissions, isolate processes where appropriate, control network access, protect secrets, log tool calls, and require confirmation before consequential actions. A portable plugin is easier to load; that makes review and policy more important, not less.

A Low-Risk Migration Plan

1. Inventory the existing package. Separate skills, MCP servers, hooks, commands, UI, marketplace metadata, credentials, and setup scripts.
2. Add root plugin.json. Use the v1 schema and a stable lowercase name. Keep the first manifest minimal.
3. Normalize reusable skills. Place each valid skill at skills/<skill-name>/SKILL.md. Move scripts and references inside that skill directory.
4. Translate only portable MCP settings. Create root mcp.json, choose an explicit transport, keep command and arguments separate, and remove embedded secrets.
5. Preserve client-only behavior. Keep existing manifests while needed, or move custom behavior into the correct reverse-domain extension namespace.
6. Test one capability at a time. Confirm the manifest loads, then each skill, then each MCP server, then client extensions.
7. Publish a support matrix. State which clients, versions, transports, operating systems, and capabilities you actually tested.
8. Remove legacy glue last. Delete old packaging only when no supported client or distribution route depends on it.

The Release Checklist

• Manifest: root plugin.json validates against the declared 1.0.0 schema and contains no invented top-level fields.
• Name: 1-64 characters, lowercase letters, numbers, hyphens, or periods; alphanumeric at both ends; no doubled hyphens or periods.
• Skills: every skill is an immediate child of skills/, contains exactly named SKILL.md, and passes the Agent Skills rules.
• MCP: mcp.json uses the same specification version, declares one valid transport per server, and has no credentials.
• Paths: declared package-relative paths begin with ./, resolve inside the plugin root, and work on supported operating systems.
• Remote endpoints: non-loopback URLs use HTTPS; redirect behavior and authentication are tested.
• Failure isolation: disable one server and corrupt one skill in a test copy; verify the client reports the problem while loading healthy components.
• Permissions: document tools, data touched, network destinations, write operations, and human approval points per client.
• Portability: run the same three representative tasks in every claimed client and save evidence, not just screenshots of successful installation.
• Versioning: pin a release, publish a changelog, define update behavior, and keep a rollback package.

Official Video Chapters

Bottom Line

Agent Plugins solves a real but bounded problem: how to package agent capabilities so multiple products can find the same reusable skills and MCP configurations. Its restraint is a strength. The format creates a stable core without pretending that permission systems, marketplaces, user interfaces, authentication, and runtimes have already converged.

For plugin authors, the sensible move is additive adoption. Put portable identity at root plugin.json, reusable workflows in skills/, and safe connection metadata in mcp.json. Keep richer client behavior in explicit extension layers, publish an honest support matrix, and test the package in every product you name. One package can travel farther now, but trustworthy execution still has to be earned in each host.

Sources and Further Reading

• Official video: Introducing Agent Plugins
• Agent Plugins official site
• Agent Plugins Specification v1.0.0
• Official author quickstart
• Official compatible-client matrix
• Specification repository, schemas, governance, and charter
• Canonical example package and migration guide
• Agent Skills specification
• Model Context Protocol documentation
• OpenAI Plugins documentation
• OpenAI: package a plugin for ChatGPT and Codex