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.

{
  "$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. Clients do not recursively search deeper descendants.

SKILL.md Format

---
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:

Reference files from SKILL.md using relative paths: See [API reference](references/api.md)

Size Guidelines

Move large reference materials to external repositories if needed.

mcp.json (MCP Servers)

Optional. Configures MCP servers the plugin provides.

{
  "$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

• 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

sse (Legacy)

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:

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

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
• Agent Plugins Website
• Plugin Manifest Schema
• MCP Configuration Schema
• Agent Skills Specification
• Kiro Powers Documentation