Agent Plugins 1.0.0

What it removes · how to install · a first runnable example

1. The spec: agentplugins/agent-plugins-spec (about 1.4k stars per the GitHub repo page, read 2026-10). spec/1.0.0.md is the normative text and schemas/1.0.0/ holds the two JSON Schemas; 1.1.0 is still a working draft. The smallest plugin:

hello-plugin/
├── plugin.json
└── skills/greet/SKILL.md

# plugin.json: only $schema and name are required
{ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin" }

Install steps for the launch clients (all from each vendor's official docs, searched 2026-10):

• VS Code: run Chat: Install Plugin From Source from the Command Palette and paste a Git repo URL. The copilot-plugins and awesome-copilot marketplaces are wired in by default; add others with chat.plugins.marketplaces.
• Copilot CLI: copilot plugin install <plugin-name>@awesome-copilot; on older versions first run copilot plugin marketplace add github/awesome-copilot. You can also list it under enabledPlugins in settings.
• github/awesome-copilot: GitHub's community marketplace, visible by default in VS Code, Copilot CLI and the Copilot app; spec plugins install from here.
• Codex: codex plugin marketplace add owner/repo to add a marketplace, codex plugin add <plugin>@<marketplace> to install; /plugins lists them interactively.
• Cursor: reads both formats, a root plugin.json (Agent Plugins) and .cursor-plugin/plugin.json (Cursor's own). For local testing drop the folder into ~/.cursor/plugins/local/ and Reload Window; marketplace plugins install with /add-plugin.
• Kiro: in the Powers panel choose "Import power from GitHub" and paste the repo URL; both plugin.json and the older POWER.md work. MCP servers inside the plugin are managed by Kiro, not written into your ~/.kiro/settings/mcp.json, and switch on and off with the power.

Mechanism: why it can work across clients

1. Fixed locations, no configuration

Skills are found only as SKILL.md in the immediate children of skills/; the spec explicitly forbids recursive search. Each skill follows the Agent Skills spec, and a non-conforming one is skipped while the rest of the plugin loads. MCP is read only from the root mcp.json, never from plugin.json.

2. MCP config is a closed union

Every server must state its type: stdio, streamable-http or legacy sse; one extra field makes that entry invalid. The Design Decisions section explains why: existing clients use incompatible MCP config shapes and infer transports differently. A client only needs to support one of stdio or streamable-http and skips entries it can't run.

{ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "lint": { "type": "stdio", "command": "./bin/lint-server",
              "args": ["--cache", "${PLUGIN_DATA}/cache"] } } }

Only two placeholders expand: ${PLUGIN_ROOT} (the plugin root) and ${PLUGIN_DATA} (a client-managed writable directory that survives updates). Every path must start with ./ and must not resolve outside the plugin root.

3. Client-specific extras go in reverse-domain directories

Hooks, commands, agents, rules and LSP servers are explicitly out of v1 as "too client-specific". They go in directories like com.github.copilot/ or under the extensions field of plugin.json; clients must ignore namespaces they don't implement, without validating them.

Real usage and limits: one folder for Claude Code and the other five

my-tools/
├── plugin.json                # Agent Plugins: $schema + name
├── .claude-plugin/plugin.json # Claude Code manifest (optional)
├── skills/review/SKILL.md     # shared, written once
├── mcp.json                   # explicit type + ${PLUGIN_ROOT}
├── .mcp.json                  # Claude Code copy + ${CLAUDE_PLUGIN_ROOT}
└── com.github.copilot/hooks/  # one client's extras live here

Two checks: on the Claude Code side, claude --plugin-dir ./my-tools loads it directly and claude plugin validate ./my-tools checks the manifest; for the skill layer, use skills-ref validate from agentskills/agentskills. The spec's own FUTURE_CONSIDERATIONS admits there is no official validator yet, so on the Agent Plugins side you rely on the two JSON Schemas and each client's error messages.

Criteria: when to package as an Agent Plugin

• One skill, one client → don't package. A single SKILL.md in the skills directory is enough.
• Several skills plus an MCP server, and teammates split between Copilot and Cursor → package it, put it in one Git repo, and let each person install it as above.
• The real value is in hooks or subagents → v1 can't help; write those once per client, each in its own namespace.
• The team uses only Claude Code → stay with .claude-plugin/ and a marketplace; see plugin management in Skill 34.

Costs and alternatives

1. The trust boundary is left to clients

The spec explicitly does not define installation, permission or trust models, distribution and marketplaces, registries, or OAuth and credentials. FUTURE_CONSIDERATIONS lists what's pending: permission declarations in the manifest, signatures and provenance, secret injection, enterprise allowlists. None of that is in 1.0. A stdio MCP server is a program that runs on your machine; review it with the checklists in Skill 30 and Skill 12.

2. "Works across clients" is not "works equally well"

The spec says where a client finds components, not how it exposes a skill to users or models. The same skill can trigger differently, get a different namespace, and cost different context in each client; run it at least once in each before publishing broadly.

3. Two configs drift

Supporting Claude Code means two MCP configs, which is one more place for things to drift. There are no dependency declarations either (also on the pending list), so plugins can't reference each other.