agent-plugins-reference

# Agent Plugins Specification Reference ## Overview Agent Plugins is an open, vendor-neutral specification (v1.0.0) maintained by a Technical Steering Committee including Amazon, Cursor, Microsoft, OpenAI, and Vercel. It defines a portable package format for Agent Skills and MCP servers that compatible clients can discover and load consistently. A power built to the agent-plugins standard is portable across any conformant client. ## Plugin Structure ``` my-plugin/ ├── plugin.json # Required manifest ├── skills/ # Agent Skills (optional) │ └── my-skill/ │ ├── SKILL.md # Required per skill │ ├── scripts/ # Helper scripts (optional) │ ├── references/ # Reference docs (optional) │ └── assets/ # Templates, configs (optional) └── mcp.json # MCP server config (optional) ``` ## plugin.json (Manifest) Required. Identifies the plugin and the spec version it targets. ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "my-plugin", "version": "1.0.0", "description": "What this plugin does", "author": { "name": "Your Name", "url": "https://example.com" }, "keywords": ["keyword1", "keyword2"], "license": "MIT", "repository": "https://github.com/example/my-plugin" } ``` **Required fields:** - `$schema` - Must be `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json` - `name` - Lowercase, 1-64 chars, only `a-z`, `0-9`, `-`, `.`. No consecutive `--` or `..`. Must start/end alphanumeric. **Optional metadata fields:** - `version` - Semantic Versioning recommended - `description` - Short description - `author` - Object with `name`, `email`, `url` (all optional strings) - `homepage` - Documentation URL - `repository` - Source repo URL - `license` - SPDX identifier recommended - `keywords` - Array of search/discovery tags The schema defines a fixed set of top-level fields; unknown fields are reported and ignored but do not invalidate the manifest. ## skills/ (Agent Skills) Each immediate subdirectory of `skills/` containing a `SKILL.md` file is one skill. Skills follow the [Agent Skills specification](https://agentskills.io/specification). Clients do not recursively search deeper descendants. ### SKILL.md Format ```markdown --- name: "my-skill" description: "What this skill does. Use when the user needs X." license: "MIT" compatibility: "Works with Kiro, Claude Code, Cursor" metadata: author: "your-name" version: "1.0.0" --- # My Skill ## Overview What this skill does and when to use it. ## Prerequisites Checklist - [ ] Requirement 1 - [ ] Requirement 2 ## Step-by-Step Guide ### 1. First Step Instructions with code examples... ## Troubleshooting ### Error: "common error" **Solution:** How to fix it. ``` **Required frontmatter fields:** - `name` - Lowercase with hyphens, 1-64 chars, must match directory name exactly - `description` - Max 1024 chars, start with verb, include when to use **Optional frontmatter fields:** - `license` - SPDX identifier - `compatibility` - Environment requirements (max 500 chars) - `metadata` - Arbitrary key-value pairs (author, version, created, etc.) - `allowed-tools` - Experimental glob patterns for tool restrictions ### Skill Subdirectories All optional: | Directory | Purpose | Guidelines | |-----------|---------|-----------| | `scripts/` | Executable helper scripts | Any language, < 500 lines each | | `references/` | Additional documentation | API refs, extended examples, checklists | | `assets/` | Templates, config files | Static resources referenced from SKILL.md | Reference files from SKILL.md using relative paths: `See [API reference](references/api.md)` ### Size Guidelines | Component | Recommendation | Rationale | |-----------|---------------|-----------| | SKILL.md | 400-800 lines | Lightweight discovery and loading | | Individual scripts | < 500 lines | Easy to understand and modify | | Total skill directory | < 2 MB | Quick download and indexing | Move large reference materials to external repositories if needed. ## mcp.json (MCP Servers) Optional. Configures MCP servers the plugin provides. ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "my-server": { "type": "stdio", "command": "npx", "args": ["-y", "@example/mcp-server"], "env": { "CONFIG": "${PLUGIN_ROOT}/config.json" } } } } ``` **Required fields:** - `$schema` - Must be `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json` - `mcpServers` - Object with named server entries **Server transport types:** ### stdio | Field | Type | Required | Description | |-------|------|----------|-------------| | `type` | `"stdio"` | Yes | Selects stdio transport | | `command` | string | Yes | Single executable token (bare name or `./` relative) | | `args` | string[] | No | Arguments passed to executable | | `env` | object of strings | No | Environment variables (cannot contain `PLUGIN_ROOT` or `PLUGIN_DATA` keys) | | `cwd` | string | No | Working directory (must start with `./`, `${PLUGIN_ROOT}`, or `${PLUGIN_DATA}`) | - `command` must be a single token, not a shell command string - Bare names resolve via platform executable search - Plugin-relative paths (`./bin/server`) resolve against plugin root - When `cwd` is omitted, the plugin root is used ### streamable-http | Field | Type | Required | Description | |-------|------|----------|-------------| | `type` | `"streamable-http"` | Yes | Selects Streamable HTTP transport | | `url` | string | Yes | Absolute HTTP/HTTPS URL (HTTPS required for non-loopback) | | `headers` | object of strings | No | Fixed HTTP headers (no secrets, no expansion) | ### sse (Legacy) | Field | Type | Required | Description | |-------|------|----------|-------------| | `type` | `"sse"` | Yes | Selects deprecated HTTP+SSE transport | | `url` | string | Yes | Absolute HTTP/HTTPS URL | | `headers` | object of strings | No | Fixed HTTP headers | ### Loading Rules - Invalid `mcp.json` (bad JSON, unsupported schema version, schema mismatch with plugin.json) disables MCP for that plugin but does not prevent other components from loading - Invalid individual server entries are skipped; other servers continue loading - Unsupported transport types are skipped - Connection failures are non-fatal to other components ## Environment Variables and Placeholder Expansion Clients provide two variables to stdio subprocesses: | Variable | Purpose | Contents | |----------|---------|----------| | `${PLUGIN_ROOT}` | Bundled read-only files | Absolute path to plugin directory | | `${PLUGIN_DATA}` | Persistent writable state | Absolute path to client-managed data directory | **Expansion applies to:** `args` elements, `env` values, `cwd` string **Expansion does NOT apply to:** `command`, `url`, header names/values, `env` keys Expansion is single-pass, non-recursive. Unrecognized placeholder-like text remains literal. No other placeholder or environment-variable expansion is performed. **Use `PLUGIN_ROOT` for:** referencing bundled scripts, binaries, config files that ship with the plugin. **Use `PLUGIN_DATA` for:** installed dependencies, generated code, caches, persistent state that survives plugin updates. ## Mapping: Kiro Powers to Agent Plugins | Kiro Power (old) | Agent Plugin (new) | Notes | |------------------|-------------------|-------| | POWER.md frontmatter | `plugin.json` | name, description, keywords, author move here | | POWER.md body | `skills/*/SKILL.md` | Split into discrete skills | | `steering/*.md` | `skills/*/references/*.md` or separate skills | Depends on independence | | `mcp.json` | `mcp.json` with `$schema` + `type` per server | Add schema ref and transport type | | N/A | `skills/*/scripts/` | Executable helper scripts | | N/A | `skills/*/assets/` | Templates and configs | ## Best Practices ### Naming - Plugin names: lowercase, hyphens/periods, 1-64 chars (`my-plugin`, `acme.tools`) - Skill names: match directory name exactly, lowercase with hyphens - Keep names descriptive but concise ### Description Writing - Start with a verb: "Generate...", "Monitor...", "Deploy..." - Include when to use it: "Use when uploading datasets or creating cards." - Max 1024 chars for skill descriptions ### Skill Organization - One skill per concern. Don't lump unrelated workflows into one skill. - Keep SKILL.md focused (400-800 lines). Move heavy reference to `references/`. - Include copy-paste-ready code examples in fenced blocks. - Use checklists for prerequisites. ### MCP Configuration - Always include the `$schema` field - Always include `type` on each server entry - Use `${PLUGIN_ROOT}` for bundled files, `${PLUGIN_DATA}` for generated/cached state - Never embed secrets in `env` or `headers` ### Keywords - Use 5-7 specific keywords that match how users search - Avoid overly broad terms ("test", "api", "data") that cause false activations - Include the tool/service name and specific domain terms ## References - [Agent Plugins Specification v1.0.0](https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md) - [Agent Plugins Website](https://agent-plugins.org/) - [Plugin Manifest Schema](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) - [MCP Configuration Schema](https://agent-plugins.org/schemas/1.0.0/mcp.schema.json) - [Agent Skills Specification](https://agentskills.io/specification) - [Kiro Powers Documentation](https://kiro.dev/docs/powers/)