Agent Plugins 1.0 is a published, vendor-neutral specification for packaging reusable agent extensions in one directory. A conforming package has a root plugin.json manifest and may contain Agent Skills under skills/ and MCP server configuration in mcp.json.

Version 1.0 standardizes the portable package and discovery rules. It does not standardize a marketplace, archive format, install command, update service, user interface, permission screen, or the way a client exposes a skill to a model. Those behaviors belong to each client.

That distinction prevents a common mistake: seeing a vendor's "plugin" feature and assuming every field, hook, command, or install flow belongs to the Agent Plugins standard. It does not.

What the 1.0 standard actually covers

The package is a self-contained directory. Its portable floor consists of:

  • exactly one root plugin.json;
  • optional skills at immediate child directories under skills/;
  • optional MCP server entries in root mcp.json;
  • fixed discovery locations rather than paths configured in the manifest;
  • version matching between the two root schemas;
  • path-containment and partial-failure rules;
  • a namespace for explicit client extensions.

Agent Plugins 1.0 defines exactly two portable component types: Agent Skills and MCP servers. Commands, hooks, rules, subagents, LSP servers, UI panels, and similar features are outside the 1.0 portable format.

A client can conform while supporting only skills or only MCP. Unsupported components must be ignored. Portability therefore means a client can understand the pieces it implements; it does not mean every conforming client provides every capability.

The standard package layout

deployment-tools/
├── plugin.json
├── skills/
│   ├── release-check/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── release-policy.md
│   └── incident-summary/
│       └── SKILL.md
├── mcp.json
├── com.example.client/
│   └── client-specific-files/
├── LICENSE
└── CHANGELOG.md

plugin.json, skills/, and mcp.json have standardized meanings. com.example.client/ is an example of a namespaced client extension directory; other clients ignore it unless they own and implement that namespace. LICENSE and CHANGELOG.md are useful package files but are not portable component types.

plugin.json: the portable manifest

The smallest valid manifest is:

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

Both fields are required. The name must be 1–64 characters, use lowercase letters, numbers, hyphens, or periods, start and end with an alphanumeric character, and avoid consecutive hyphens or periods.

A fuller manifest can use only the standard top-level fields:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "example.deployment-tools",
  "version": "1.0.0",
  "description": "Read-only release and incident workflows.",
  "author": {
    "name": "Example Engineering",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/agent-tools",
  "repository": "https://github.com/example/deployment-tools",
  "license": "Apache-2.0",
  "keywords": ["release", "incident", "operations"],
  "extensions": {
    "com.example.client": {
      "displayGroup": "Operations"
    }
  }
}

The schema is closed. Client-specific data belongs under extensions, keyed by a reverse-domain namespace. Do not place skills, mcpServers, commands, or a vendor's private fields at the top level.

Semantic Versioning and SPDX license identifiers are recommended, but the 1.0 specification generally validates those metadata values by JSON type rather than proving the strings are valid SemVer, URLs, email addresses, or SPDX identifiers. Your publishing checks can be stricter.

How skills are discovered

Skills live in immediate child directories of skills/:

skills/
├── release-check/
│   └── SKILL.md
└── incident-summary/
    └── SKILL.md

The client does not recursively search arbitrary depths. Each discovered SKILL.md must conform to the separate Agent Skills specification. Agent Plugins defines where the skill is found inside a plugin; Agent Skills defines its frontmatter, instructions, and support-file conventions.

If one skill is invalid, the client skips that skill and continues loading independent components. A broken skill should not disable a valid MCP server or neighboring skill.

For the instruction-writing layer behind a skill, see prompt engineering for code.

How MCP servers are declared

MCP wire behavior and lifecycle come from the Model Context Protocol. Agent Plugins 1.0 adds a portable mcp.json configuration shape so clients can locate and connect to packaged servers without interpreting each vendor's native config.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "release-data": {
      "type": "stdio",
      "command": "./bin/release-server",
      "args": ["--data", "${PLUGIN_DATA}/release-data"],
      "env": {
        "POLICY_FILE": "${PLUGIN_ROOT}/config/policy.json"
      },
      "cwd": "${PLUGIN_ROOT}"
    },
    "status-api": {
      "type": "streamable-http",
      "url": "https://status.example.com/mcp",
      "headers": {
        "X-Client": "deployment-tools"
      }
    }
  }
}

The top-level object may contain only $schema and mcpServers. The schema version must match plugin.json.

The 1.0 transport variants are:

  • stdio: a local process, with a single executable token in command;
  • streamable-http: a remote MCP endpoint;
  • sse: the legacy HTTP+SSE transport, with optional client support.

An MCP-capable conforming client must support at least one of stdio or Streamable HTTP and should support both. It may skip an unsupported transport without rejecting the rest of the plugin.

PLUGIN_ROOT and PLUGIN_DATA

For stdio servers, clients provide:

  • PLUGIN_ROOT: the resolved, read-only package location conceptually used for bundled files;
  • PLUGIN_DATA: a client-managed writable directory for persistent installed state, dependencies, generated files, and caches.

The specification requires expansion of exactly those placeholders in args, env values, and cwd. It does not expand them in command, URL fields, headers, environment keys, or component locations.

This split matters during updates. Package files may be replaced; writable state should live outside them in PLUGIN_DATA.

Loading and installation are different concepts

The standard defines what a conforming client does after it is given a plugin directory:

  1. locate root plugin.json;
  2. select locally supported rules from the $schema identifier;
  3. validate the manifest;
  4. discover each supported component at its fixed location;
  5. validate skills and MCP entries with their own failure boundaries;
  6. map portable MCP configuration to the client's runtime;
  7. expose or execute supported components according to client policy.

The standard does not define how the directory arrived. A client might copy a local folder, clone a Git repository, unpack a signed archive, use an enterprise catalog, or expose no install UI at all. Do not publish agent-plugin install ... as a universal command; no such portable command exists in 1.0.

Likewise, update checks, lockfiles, signatures, dependency installation, consent, activation, and uninstall cleanup are client concerns unless a future specification standardizes them.

Vendor-neutral core versus product behavior

Use this test when reading documentation:

> Would another conforming client have to implement this exact field, file location, or behavior?

If the answer comes from a MUST in the Agent Plugins 1.0 specification, it is portable. If it appears only in OpenAI, Cursor, Anthropic, Microsoft, Vercel, or another vendor's docs, it is product behavior.

Examples:

  • Root plugin.json with the canonical schema: portable 1.0.
  • Skills under immediate child directories of skills/: portable 1.0.
  • Root mcp.json with one of the defined transports: portable 1.0.
  • A branded marketplace or one-click install button: vendor-specific.
  • A slash command generated from a skill: vendor-specific.
  • Cursor rules, hooks, modes, or UI controls: Cursor-specific unless represented in an explicit extension namespace.
  • OpenAI API tools, app UI, or account installation behavior: OpenAI-specific, not Agent Plugins 1.0.

This guide does not claim that a particular OpenAI or Cursor release imports every Agent Plugins 1.0 component. Product support changes independently of the package specification. Verify current client documentation and run a compatibility test.

The Cursor AI guide explains that product's broader coding workflow. It should not be read as the Agent Plugins standard.

Build a portable plugin step by step

We will package two read-only release skills and one optional MCP server.

Step 1: state the portability target

Write down:

  • specification: Agent Plugins 1.0.0;
  • required client capability: Agent Skills;
  • optional capability: stdio MCP;
  • supported operating systems;
  • runtime dependencies;
  • expected permissions;
  • behavior when MCP is unavailable.

This prevents a "portable" label from hiding a hard dependency on one client's hook system.

Step 2: create and validate plugin.json

Start with only $schema, name, version, description, license, and repository metadata. Validate against the canonical 1.0.0 schema. Keep client settings out until the portable core works.

Step 3: add one skill

---
name: release-check
description: Produce a read-only release-readiness report. Use for pre-release checks, version review, migration risk, or rollback planning. Never deploy.
---

# Release check

1. Inspect repository release documentation and version files.
2. If an MCP tool named `release_status` is available, use it only for
   read-only status data.
3. If that tool is unavailable, continue with repository evidence and state
   the missing data.
4. Return blockers, checks run, uncertainty, and a draft rollback plan.

The skill degrades gracefully when MCP is absent. That matters because clients may support skills without MCP.

Step 4: add mcp.json only if live tools earn their cost

Add a server when the workflow needs live deployment status that files cannot provide. Keep the server's tool surface narrow: release_status and migration_status are easier to authorize and understand than a generic run_operation.

Do not bundle credentials. The specification explicitly treats configured env and HTTP headers as visible package data, not secret storage. Agent Plugins 1.0 defines no portable OAuth configuration or credential-reference field; authorization discovery and credential storage are client-managed.

Step 5: test partial failure

Your test matrix should include:

  • valid manifest, skill, and MCP;
  • valid skill with no mcp.json;
  • invalid one skill alongside a valid skill;
  • valid skills with unsupported MCP transport;
  • MCP connection or authentication failure;
  • unsupported schema version;
  • path escape through a symlink or ../;
  • missing runtime dependency.

The expected result is not always "reject everything." The specification intentionally isolates many component failures.

Step 6: add a namespaced extension last

Only add extensions["com.example.client"] or a matching top-level extension directory when one client needs extra behavior. Document that the extension is optional and identify the fallback on clients that ignore it.

Never disguise a required vendor extension as portable support.

Portability limits you should plan for

Capability support differs

A client may support only Agent Skills. Another may support only MCP. Another may support both but not your declared transport. Publish a capability matrix based on tests, not assumptions.

Runtime environments differ

A stdio server that invokes Bash, Node.js, Python, Docker, or a native binary depends on what the client host provides. Document compatibility and prefer bundled, platform-appropriate executables when practical.

User experience is not portable

The standard does not prescribe activation phrases, menus, command palettes, permission dialogs, logs, or error rendering. A plugin can conform and still feel different across clients.

Authentication is client-managed

Remote MCP endpoints may need authorization, but Agent Plugins 1.0 does not package portable secrets or OAuth settings. Plan a documented client-specific onboarding path and a safe unauthenticated failure.

Client extensions reduce reach

Namespaced extensions are valid, but only the owning client understands them. Keep the core useful without the extension whenever possible.

Trust and security

A plugin can contain executable MCP servers, instructions that influence model behavior, and files that a client may read. A valid schema proves structure, not trust.

For plugin authors

  • Keep all package-relative paths inside the plugin root.
  • Do not rely on symlinks, junctions, or reparse points that escape the root.
  • Do not embed credentials in plugin.json, mcp.json, headers, environment values, scripts, or examples.
  • Make subprocess commands single executable tokens with arguments separated.
  • Use HTTPS for non-loopback remote MCP endpoints.
  • Request the smallest tool and data scope.
  • Validate tool inputs, enforce authorization server-side, rate-limit calls, and sanitize outputs.
  • Make sensitive writes explicit and reversible.
  • Publish source, license, checksums or signatures where your distribution system supports them, and a change history.

For clients and installers

  • Resolve filesystem paths and reject escapes before reading or execution.
  • Validate against locally trusted schemas; the specification says clients must not fetch a schema while loading a plugin.
  • Show the package origin, requested processes, remote origins, and effective permissions before enabling it.
  • Treat MCP tool annotations and returned content as untrusted.
  • Apply timeouts, output limits, confirmation for sensitive operations, and audit logs.
  • Isolate plugin data and avoid inheriting unnecessary ambient secrets.
  • Review updates before replacing a trusted version.

Prompt injection still applies

A skill, tool result, web page, issue, or reference file may contain instructions that conflict with the user's goal. Package conformance does not create an instruction trust hierarchy. Clients should preserve system and user policy, label untrusted data, constrain tools, and require approval for sensitive actions.

Plugin vs skill vs MCP

Choose an Agent Skill when

You need portable procedural knowledge, checklists, examples, and optional deterministic helpers loaded on demand. A skill can work without a live service.

Choose MCP when

The agent needs a protocol-defined connection to tools, resources, or prompts backed by a process or remote service. MCP provides runtime capability; it does not package the team's full operating procedure by itself.

Choose an Agent Plugin when

You want one distributable directory that groups one or more skills, optional MCP servers, shared metadata, and clearly separated client extensions.

The relationship is:

Agent Plugin (package and discovery)
├── Agent Skills (procedural knowledge)
└── MCP servers (runtime tools and data)

A skill can be distributed without a plugin. An MCP server can be configured without a plugin. A plugin is useful when the components form one coherent capability and should be versioned together.

For provider-level API choices rather than package formats, see OpenAI vs Anthropic APIs.

Common mistakes

Putting component config in plugin.json

plugin.json does not contain a skills list or inline MCP config. Use fixed skills/ and mcp.json locations.

Calling every vendor extension portable

Client hooks and commands belong in a documented reverse-domain extension namespace, and other clients may ignore them.

Shipping secrets in headers

Headers in mcp.json are visible package data. Use client-managed authorization.

Assuming validation means safe

JSON Schema cannot tell you whether a bundled executable deletes files or exports source code. Review behavior and run in a restricted environment.

Failing the whole plugin for one broken server

The 1.0 rules include narrow failure boundaries. Preserve valid independent skills and server entries where the specification requires it.

Advertising universal installation

There is no standard marketplace or install command in 1.0. Give separate, tested instructions for each supported client.

FAQ

Is Agent Plugins 1.0 an OpenAI plugin format?

No. It is a vendor-neutral specification maintained by the Agent Plugins project. OpenAI products may have their own plugin, tool, app, or integration behavior. Similar terminology does not make those behaviors part of this standard.

Is it a Cursor plugin format?

No. Cursor-specific features and installation behavior are separate unless Cursor explicitly implements the standard or owns a declared extension namespace. Verify current product documentation.

Does every plugin need both skills and MCP?

No. The manifest is required; skills and mcp.json are optional. A conforming client must support at least one component type.

Can plugin.json point to a different skills folder?

No. Version 1.0 uses fixed discovery locations and does not allow the manifest to override them.

Can mcp.json contain environment-variable secrets?

Do not use it as a secret mechanism. Configured environment values and headers are package-visible. The client owns credential storage and authorization.

How are plugins installed?

That is outside 1.0. A client receives a directory through its own local, repository, catalog, archive, or managed-distribution flow.

What happens when one MCP server fails?

The client should skip or report the failed entry and continue loading other independent servers and components according to the specification's failure rules.

Should I target the 1.1 working draft?

Use the published version your target clients support unless you are explicitly testing draft behavior. A draft can change and should not be advertised as 1.0 conformance.

Release checklist

  • [ ] Root manifest uses the canonical 1.0.0 schema.
  • [ ] Name and all closed-schema fields validate.
  • [ ] Skills are immediate children of skills/ and validate independently.
  • [ ] Root mcp.json version matches plugin.json.
  • [ ] MCP entries use defined transports and contained paths.
  • [ ] No secrets appear in package data.
  • [ ] Skills remain useful when optional MCP is unavailable.
  • [ ] Client extensions use owned reverse-domain namespaces.
  • [ ] Partial-failure and unsupported-component cases are tested.
  • [ ] Each target client's install and runtime behavior is documented separately.
  • [ ] Source, license, version, and rollback path are available.

Continue learning

Sources

The first source is normative for Agent Plugins 1.0. Product install flows and UI behavior are deliberately not generalized from OpenAI, Cursor, or any other vendor. Client compatibility must be tested against current product documentation.

ai-agentsagent-pluginsagent-skillsmodel-context-protocolinteroperability