Agent Plugins 1.0: Portable Skills and MCP Guide

Direct answer

Agent Plugins 1.0.0 is an open, vendor-neutral packaging standard for AI-agent extensions. It gives a plugin a predictable root plugin.json manifest, a skills/ directory for reusable Agent Skills, and an optional mcp.json file for MCP server configuration. The goal is simple: authors package portable components once, while compatible clients discover and load them without each platform inventing a different directory layout.

It is important to understand what the standard does not do. Agent Plugins is a packaging and discovery contract, not a universal marketplace, permission system, sandbox, billing layer, or guarantee that every client supports every component. Installation, trust, policy, and client-specific features remain the responsibility of the agent client.

Key takeaways

• Agent Plugins 1.0.0 standardizes the portable packaging of Agent Skills and MCP servers.
• A conforming package must put plugin.json at its root and use the canonical 1.0.0 schema identifier.
• Skills live below skills/; MCP configuration lives in root mcp.json.
• The v1 format intentionally leaves permissions, installation, distribution, and sandboxing to clients.
• Launch support includes ChatGPT and Codex, Cursor, GitHub Copilot, Kiro, and VS Code according to the launch documentation.
• Treat every plugin as executable supply-chain input: validate provenance, inspect MCP commands, restrict credentials, and test in an isolated workspace.

Why a shared agent-plugin format matters

Agent clients have converged on similar building blocks but not on a shared package boundary. One tool may expect a skill in a client-specific folder, another may use a different manifest, and a third may require separate MCP configuration. The component itself can be reusable while its packaging is not.

Agent Plugins addresses that distribution problem without trying to redesign either underlying component. Agent Skills provide instructions and resources that guide an agent through a task. MCP servers expose tools, resources, or prompts through a protocol connection. The plugin format puts those pieces in one predictable directory so a client can discover the parts it supports.

The practical value is highest for teams maintaining internal engineering assistants, documentation workflows, security skills, data connectors, or repository automation. A portable package can reduce duplicated setup work and make migrations between supported clients less painful.

The v1 package layout

A plugin can be as small as a manifest and one skill, or it can include both skills and MCP servers:

1my-plugin/
2├── plugin.json
3├── skills/
4│   └── summarize/
5│       ├── SKILL.md
6│       ├── scripts/
7│       └── references/
8├── mcp.json
9├── LICENSE
10└── CHANGELOG.md

The smallest useful manifest is deliberately minimal:

1{
2  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3  "name": "repo-summarizer"
4}

The official specification requires the root manifest and defines a closed set of portable metadata fields, including name, version, description, author, homepage, repository, license, keywords, and extensions. The plugin name must use lowercase letters, numbers, hyphens, or periods, begin and end with an alphanumeric character, and avoid consecutive -- or .. sequences.

A skill is discovered from a subdirectory containing SKILL.md:

1Read the repository map first. Produce a concise summary with links to the files that support each claim.

The frontmatter shown here belongs inside the skill format, not in the article body. Keep the skill instructions scoped, testable, and free of assumptions about a particular client. If a skill needs scripts or reference material, keep those files inside the plugin root and use plugin-relative paths where the specification requires them.

An MCP configuration can expose a server through a portable definition. For example, a local server entry may look like this:

1{
2  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
3  "mcpServers": {
4    "repo-tools": {
5      "type": "stdio",
6      "command": "./bin/repo-tools",
7      "cwd": "./data"
8    }
9  }
10}

The ./ prefixes matter for package-relative paths. The specification requires clients to reject paths that resolve outside the plugin root. This containment rule helps prevent a package from silently pointing its configured executable or working directory at an unrelated location. It is not, by itself, a sandbox for the subprocess; operating-system permissions and client policy still matter.

How clients discover and load a plugin

A conforming client first checks plugin.json, validates the manifest, and then discovers supported components at fixed locations. It looks below skills/ for skills and reads mcp.json for MCP servers. A missing component location is not automatically an error. This allows a skills-only or MCP-only package.

Components are validated independently. That is a useful design choice: one invalid skill should not necessarily disable an otherwise valid MCP entry, and vice versa. Clients can also use namespaced extension directories or manifest data for client-specific behavior. Other clients should ignore those namespaces rather than interpreting them as portable components.

The resulting flow is small enough to implement and inspect:

That last policy step is where much of the real security work lives. The format tells a client where to find a component; it does not tell the client whether the component deserves access to a filesystem, network, credential, or production system.

What Agent Plugins standardizes—and leaves open

This boundary is intentionally narrow. Vercel’s launch post says Agent Plugins 1.0.0 focuses on Agent Skills and MCP servers because both already have meaningful specifications and adoption. Commands, hooks, and agents remain client-specific for now. Expanding the portable surface too quickly could create a nominal standard whose behavior still differs everywhere.

A safe adoption workflow for developers

1. Pin and validate the specification

Use the canonical schema URL and treat the specification as versioned input. Do not assume that a blog post or a client’s plugin format is identical to the vendor-neutral contract. Validate JSON before publishing and test the package with each target client.

2. Separate portable content from client extensions

Put reusable skills and MCP definitions in the portable locations. Keep client-specific hooks, commands, or policy under the client’s documented namespace. This makes the package understandable to another client and makes portability gaps explicit instead of accidental.

3. Review MCP commands as code

An MCP entry can launch a process or connect to a remote service. Inspect the command, arguments, working directory, environment variables, and network destination. Prefer narrow tools over a generic shell bridge. A package that asks for broad filesystem access or ambient credentials should be treated as high risk regardless of its manifest.

4. Install in an isolated workspace first

Use a disposable repository, a test account, and least-privilege credentials. Log process launches and tool calls. Confirm which files are read or modified, which network requests occur, and whether the client asks for approval before side effects. Only then consider team-wide distribution.

5. Make trust visible to users

Ship a license, repository link, changelog, security contact, and clear description of side effects. A portable package should be easier to audit, not easier to run blindly. Pin versions for production workflows and review updates like dependency upgrades.

Agent Plugins compared with MCP and Agent Skills

Agent Plugins does not replace MCP or Agent Skills. MCP remains the runtime protocol for connecting an agent to tools and data. Agent Skills remain the instruction-and-resource format for reusable workflows. Agent Plugins packages those existing pieces together for distribution.

That distinction matters when designing an architecture. If your problem is request routing, session lifecycle, or server scaling, read the MCP stateless migration guide. If you need to embed a coding runtime with sessions, tools, and approvals, the GitHub Copilot SDK GA guide covers a different layer of the stack. And if a plugin will operate inside an autonomous coding workflow, pair it with the controls described in harness engineering for AI coding agents.

Common mistakes and debugging

Treating the format as a marketplace

Agent Plugins defines a package contract, not discovery economics. A client may install from a marketplace, repository, local directory, or enterprise registry. Check the client’s provenance and update behavior separately.

Putting the manifest in a client-specific folder

The portable manifest is plugin.json at the plugin root. A client-specific .codex-plugin/plugin.json or another legacy layout may be useful to that client, but it is not a substitute for the root Agent Plugins manifest.

Using unsafe relative paths

Commands such as ../bin/server, or paths without the required ./ form where a plugin-relative path is expected, can fail validation. Keep executable files and working directories inside the package and test path resolution after extraction, not only in the source checkout.

Assuming support means identical behavior

A client may support skills but not MCP, or may support the portable component while adding its own approval, environment, or sandbox rules. Build a small compatibility matrix and test the actual versions your team deploys.

Debugging the wrong layer

When loading fails, first validate JSON and fixed locations. Next inspect client support and extensions. Finally inspect permissions, credentials, subprocess startup, and network policy. This order separates package errors from runtime policy errors.

FAQ

Is Agent Plugins an OpenAI-only standard?

No. Vercel says it initiated the proposal and that representatives from AWS, Anysphere/Cursor, GitHub, Microsoft, OpenAI, and Vercel refined the specification. The project is openly licensed with a multi-vendor steering committee.

Does one plugin run everywhere automatically?

Not necessarily. A compatible client can discover the portable parts, but support is component-specific and client policy still controls installation and execution. Test each target client.

Can a plugin contain arbitrary executable code?

A package can include scripts and configure MCP processes, but the standard does not make that code safe. Treat scripts and servers as third-party software, review them, isolate them, and restrict credentials.

Should teams adopt it now?

It is a sensible format to evaluate if you maintain skills or MCP integrations for multiple supported clients. Pin the 1.0.0 draft, validate packages in CI, and avoid making business-critical portability assumptions until your target clients demonstrate stable support.

Conclusion

Agent Plugins 1.0.0 standardizes a missing layer in the agent ecosystem: how reusable skills and MCP connections travel as a package. Its restraint is both its strength and its limitation. A small manifest and fixed layout can improve portability, but trust, permissions, installation, sandboxing, and operational governance remain outside the format.

For developers, the right mental model is “portable packaging, not portable safety.” Build a clean package, validate it, document its side effects, and run it under explicit policy. That is how a common format becomes useful infrastructure instead of a faster way to distribute unknown code.

Sources and further reading

• Vercel: Introducing Agent Plugins — official launch announcement and package examples.
• Agent Plugins Specification 1.0.0 — normative format, validation, containment, and client-conformance rules.
• The Next Web: OpenAI and four rivals just agreed on one standard for AI agents — independent reporting on the launch, scope, and open questions.
• Agent Plugins project on GitHub — specification source and governance materials.

Visual: original Mermaid diagram by Essa Mamdani; no external image used.

Visual: Integration request flow

This original architecture diagram shows how the components described in this article fit together. It is a practical reference for deciding where authentication, validation, retries, and observability belong.

Visual reading: keep the client, policy boundary, external service, and result validation separate. This prevents an AI-generated tool call from becoming an unchecked side effect.