Build an Agent Plugin

An Agent Plugin is a self-contained directory. Every plugin has a root plugin.json; skills and MCP configuration are optional.

Create a minimal plugin

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

Create plugin.json:

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

Create the skill:

---
name: greet
description: Greet the user and offer help.
---

Greet the user and offer help.

A skills-capable client loads plugin.json, discovers the immediate children of skills/, and validates each SKILL.md against the Agent Skills specification. To add MCP servers, place mcp.json at the plugin root using the same Agent Plugins schema version.

Package boundaries

Files supplied by the package must resolve within the plugin root. Configuration fields defined as plugin-relative paths begin with ./; symlinks and equivalent filesystem mechanisms must not be used to escape the package.

Client-managed installation, distribution, enablement, updates, and user interface are outside the portable specification.

Next steps

• Manifest — Define the plugin identity, metadata, and target specification version.
• Skills — Package Agent Skills under the fixed skills/ directory.
• MCP servers — Configure local and remote MCP connections in mcp.json.
• Client extensions — Add namespaced behavior for particular clients without changing the portable contract.