Plugin authoring guide
How to Create Agent Plugins.
Learn how to create Agent Plugins with plugin.json, optional Skills, and optional MCP servers, then validate boundaries, test, and publish safely.
01
How to create Agent Plugins with a clear boundary
Start with a specific reusable job, not a broad promise. The plugin root is a self-contained directory. Every file the package asks a client to discover or execute must resolve within that root unless the specification explicitly defines a client-managed data location.
A portable package can contain only Skills, only MCP configuration, or both. “Plugin equals Skills plus MCP” is a useful mental model, not a requirement that both component types be present.
- Use a Skill for instructions, decision rules, scripts, references, and reusable workflow knowledge.
- Use MCP when the agent must connect to external tools or live context through a supported transport.
- Use a reverse-domain extension namespace only for behavior owned by a particular client.
02
Create the smallest valid plugin.json
Agent Plugins 1.0 requires plugin.json at the package root. The manifest is a closed schema: use the permitted metadata fields and place client-specific data under extensions rather than inventing portable top-level keys.
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.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "review-release",
"version": "1.0.0",
"description": "Review a release before publication",
"repository": "https://github.com/example/review-release",
"license": "MIT"
}03
Add an Agent Skill when instructions are the product
Put each Skill in an immediate child directory under skills/ and name its instruction file SKILL.md. The Skill must follow the Agent Skills specification; a client skips an invalid Skill without making every other plugin component invalid.
Write a precise description that tells an agent when the Skill applies. Keep large references or executable helpers in the Skill directory and reference them deliberately from the instructions.
skills/release-review/SKILL.md
---
name: release-review
description: Review release notes, migrations, and rollback steps before publication.
---
Check the release against references/checklist.md and report blockers first.04
Add MCP servers without embedding secrets
Portable MCP configuration lives in mcp.json at the plugin root and targets the same Agent Plugins version as plugin.json. Agent Plugins 1.0 defines stdio, Streamable HTTP, and legacy SSE entries, while each compatible client documents which transports it supports.
Never place credentials in fixed headers or committed environment values. Agent Plugins 1.0 intentionally leaves authorization interaction and credential storage to the client.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"review-data": {
"type": "stdio",
"command": "./bin/review-server",
"args": ["--data", "${PLUGIN_DATA}/reviews"]
}
}
}Editorial note: A conforming manifest proves format validity, not that a script, executable, server, or remote service is safe.
05
Validate, inspect, and test failure boundaries
Validate both JSON files against the canonical schemas without fetching schemas during plugin loading. Check that package-relative paths begin with ./ where required and cannot escape through parent segments, symlinks, junctions, or other filesystem indirection.
Test missing and invalid components separately. A missing optional location is not an error; an invalid Skill should be skipped; an invalid MCP entry should not prevent unrelated valid components from loading. Test in at least one documented compatible client and record exactly what was verified.
- Run scripts in a disposable workspace with minimum permissions.
- Exercise read-only behavior before write, network, or credentialed behavior.
- Document prerequisites, install boundaries, verification, updates, and removal.
- Pin or record the source revision used for a release and maintain a changelog.
06
Publish evidence, not marketing guesses
Publish the source repository, license, package path, version, and security-relevant prerequisites. If you distribute through a client marketplace, describe that marketplace as a distribution channel rather than part of the portable 1.0 standard.
Do not claim installation totals, ratings, official status, client compatibility, or security review unless each claim has a public source. Provide a correction channel and update the recorded modified date when behavior or compatibility changes.