MCP HubMCP Hub
POST·BUILDY

How to Build Your First Agent Plugin: A Step-by-Step Guide

AIMCP Teamon 19 days ago · 2 min read

How to Build Your First Agent Plugin: A Step-by-Step Guide

Agent Plugins (v1.0.0) is the portable packaging standard for agent components — skills and MCP servers — that works across compatible clients. In this guide you'll build a real, spec-conformant plugin from scratch: a plugin that ships one skill and one MCP server, then validate it against the official schema.

Step 1: Create the package layout

A plugin is just a directory. Create it with the two required pieces up front:

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── mcp.json

Step 2: Write the manifest

plugin.json is the only required file. The manifest schema is closed — portable top-level fields are limited to a fixed set:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "summarize.tools",
  "version": "1.0.0",
  "description": "Skills and servers for summarizing documents.",
  "author": {
    "name": "Your Name",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/summarize-tools",
  "repository": "https://github.com/you/summarize-tools",
  "license": "MIT",
  "keywords": ["summarization", "documents", "llm"]
}

Only $schema and name are required. Everything else is optional but recommended: version (SemVer), description, author, homepage, repository, license (SPDX), and keywords for discovery.

Note: the schema is closed by design. Client-specific settings belong in extension namespaces, not top-level fields.

Step 3: Add a skill

Skills live in skills/, following the Agent Skills specification. Each immediate child directory containing a SKILL.md file is one skill:

skills/
└── summarize/
    ├── SKILL.md
    ├── scripts/
    │   └── summarize.py
    └── references/
        └── guidelines.md

A minimal SKILL.md:

---
name: summarize
description: Summarize a document into key points. Use when the user asks to condense a long text.
---

# Summarize

1. Read the document from the user's input.
2. Extract the main argument, supporting points, and action items.
3. Write the summary as markdown, max 10 bullet points.

## Scripts

- `scripts/summarize.py` — CLI that takes a file path and prints a summary.

Clients discover skills by scanning skills/*/SKILL.md; they do not recurse deeper, so keep one skill per immediate subdirectory.

Step 4: Add an MCP server

If your plugin ships an MCP server, describe it in mcp.json. The format supports stdio, Streamable HTTP, and legacy HTTP+SSE transports:

{
  "servers": {
    "summarize": {
      "command": "python",
      "args": ["scripts/mcp_server.py"],
      "env": {}
    }
  }
}

Clients map this portable format to their native configuration — the field names don't need to match any client's internal format.

Step 5: (Optional) Add client extensions

Want to add behavior for a specific client without forking the core? Use a reverse-domain namespace directory named after your client, e.g. com.example.client/hooks/hooks.json. Clients look for their namespace directory at the plugin root; unknown namespaces are ignored.

Step 6: Validate

Before distributing, validate your manifest:

  1. $schema must reference the official schema URL: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.
  2. name must be present and non-empty — a missing required field makes the entire plugin invalid and clients must reject it.
  3. Check your SKILL.md frontmatter has at least name and description.
  4. Validate mcp.json against the spec's JSON schema (published on agent-plugins.org/schemas).

You can also use the spec repository's example plugin (agentplugins/agent-plugins-example) as a canonical reference, or run your plugin through AIMCP's directory submission — it validates against the official schema and reports component counts.

Step 7: Distribute

An Agent Plugin is a directory, so distribution is flexible: push it to a GitHub repository, publish it in a marketplace, or share it directly. Compatible clients discover and load plugins consistently regardless of transport.

Next steps