How to Create an AI Agent Plugin with Agent Plugins 1.0

Why Agent Plugins 1.0 Matters

AI coding tools can now share a common packaging format for reusable agent capabilities. Agent Plugins 1.0 is an open, vendor-neutral specification designed to package Agent Skills and MCP servers inside a predictable plugin directory, making it easier to build one extension that compatible AI agent clients can discover and load. The published 1.0.0 specification defines the portable contract, while installation, permissions, user interfaces, and other client-specific behavior remain outside that core standard.

That makes Agent Plugins especially interesting for developers who maintain AI tools across multiple environments. Instead of restructuring the same skill or MCP configuration for every client, you can organize the portable parts around the format defined by the specification. :contentReference[oaicite:0]{index=0}

What You Need to Build

A minimal Agent Plugin can be surprisingly small. The required root file is plugin.json. Skills can live under skills/, while MCP server definitions can be placed in an optional mcp.json file. Version 1.0 defines these two component types as its portable core.

my-ai-plugin/
├── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
└── mcp.json

You do not have to include both Skills and MCP. A plugin can contain a Skill, an MCP configuration, or both. The important part is that the package follows the published 1.0.0 rules.

Step 1: Create the Plugin Manifest

Start by creating plugin.json in the plugin root. The manifest identifies the plugin and declares which Agent Plugins specification it targets.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "code-review-helper",
  "version": "1.0.0",
  "description": "Reusable code review assistance for AI agents",
  "keywords": ["code-review", "development", "testing"]
}

The $schema and name fields are required. Other supported metadata includes the version, description, author, homepage, repository, license, keywords, and client-specific extensions. The manifest has a closed schema, so arbitrary top-level fields should not be added. :contentReference[oaicite:1]{index=1}

Step 2: Add an Agent Skill

Create a directory inside skills/ and place a SKILL.md file inside it. Agent Plugins uses immediate child directories of skills/ for Skill discovery rather than recursively searching the entire tree.

skills/
└── code-review/
    └── SKILL.md

A simple Skill can contain instructions describing the work an agent should perform.

---
name: code-review
description: Review source code for bugs, security issues, and maintainability problems.
---

Review the supplied source code.

Check for:

* Logic errors
* Security problems
* Missing error handling
* Performance issues
* Maintainability concerns

Explain important findings and suggest practical fixes.

The Skill itself follows the separate Agent Skills specification. Agent Plugins defines where that Skill is discovered and how it becomes part of the portable plugin package; it does not replace the Skill format.

Step 3: Connect an MCP Server

If your plugin needs external tools or live context, you can add an mcp.json file. Agent Plugins 1.0 supports MCP server entries with explicitly declared transports.

{
"$schema": "[https://agent-plugins.org/schemas/1.0.0/mcp.schema.json](https://agent-plugins.org/schemas/1.0.0/mcp.schema.json)",
"mcpServers": {
"local-validator": {
"type": "stdio",
"command": "./bin/validator",
"args": ["--data", "${PLUGIN_DATA}/validator"]
}
}
}

The specification supports stdio and Streamable HTTP, while support for legacy SSE is optional for clients. Explicit transport declarations are important because clients should not have to guess how an MCP server is intended to connect. ([GitHub][1])

Step 4: Keep Plugin Paths Inside the Package

One of the important security rules in Agent Plugins 1.0 is that files and directories supplied by a plugin must resolve within the plugin root. This applies to path-based configuration and is intended to prevent a plugin from escaping its own package through filesystem mechanisms such as symlinks or equivalent path tricks.

The specification also provides ${PLUGIN_ROOT} as a runtime anchor for bundled files and ${PLUGIN_DATA} for client-managed writable data. These conventions make portable configurations easier to reason about across environments. ([GitHub][1])

Step 5: Do Not Put Secrets in the Plugin

An MCP configuration may contain headers, but the specification explicitly treats configured header values as package data rather than a portable secret-storage mechanism. Credentials should not be embedded in the plugin's files.

Agent Plugins 1.0 also does not define a universal OAuth or portable credential-reference system. Authentication discovery, credential storage, and user interaction remain responsibilities of the individual client. ([GitHub][1])

Step 6: Validate the Package

Before distributing a plugin, check the package structure and manifest against the published 1.0.0 specification. At minimum, verify that plugin.json exists at the root, its required fields are valid, and the declared schema version is supported.

For a Skill-based plugin, confirm that each Skill is located directly under skills/ and contains the expected SKILL.md. For MCP integrations, check the mcp.json schema and make sure the declared transport matches the server you actually intend to run.

The official specification is the authoritative source when implementation details differ from examples or secondary documentation. ([GitHub][1])

A Complete Minimal Example

Putting the pieces together, a small code-review plugin could look like this:

code-review-helper/
├── plugin.json
└── skills/
└── code-review/
└── SKILL.md

The plugin.json identifies the package, while SKILL.md supplies the reusable behavior. You can add mcp.json later if the Skill needs access to external tools or services.

What Agent Plugins 1.0 Does Not Solve

It is easy to misunderstand the scope of the standard. Agent Plugins is primarily a packaging and interoperability layer. It does not create a universal marketplace, installer, permission system, sandbox, or user interface.

Those capabilities remain client-specific. A compatible AI agent may support Skills, MCP servers, or both, and each client controls how users install, authorize, expose, and execute those components. ([GitHub][2])

Common Mistakes to Avoid

• Using arbitrary manifest fields: Keep portable metadata inside the fields defined by the specification.
• Putting credentials in headers: Treat plugin files as distributable package data, not as a secure secret store.
• Assuming every client supports every component: Client support can differ, particularly for MCP transports.
• Putting Skills too deeply in the directory tree: Skill discovery uses immediate child directories of skills/.
• Ignoring path boundaries: Plugin-supplied paths must remain within the resolved plugin root.
• Assuming Agent Plugins replaces MCP: MCP remains a separate protocol; Agent Plugins provides a standardized way to package MCP configurations alongside Skills.

Why This Matters for AI Developers

The practical value of Agent Plugins 1.0 is less about adding another AI framework and more about reducing duplication. The standard gives developers a predictable package structure for capabilities that already exist, while leaving individual clients free to handle their own runtime behavior.

For teams building reusable AI workflows, that can make maintenance simpler. A Skill and its supporting MCP configuration can travel together instead of being manually rearranged for every compatible agent environment. GitHub's implementation announcement also notes that Agent Plugins 1.0 can be used across compatible clients, reinforcing the standard's cross-client goal. ([The GitHub Blog][3])

Final Takeaway

If you build AI agents, coding assistants, or MCP-powered developer tools, Agent Plugins 1.0 is worth learning because it establishes a common package boundary around two increasingly important building blocks: Agent Skills and MCP servers. The basic workflow is straightforward: create plugin.json, add reusable Skills under skills/, optionally define MCP servers in mcp.json, validate the package, and then test it with the clients you intend to support.

The important distinction is that portability does not mean identical behavior everywhere. Agent Plugins standardizes the package format, while installation, permissions, authentication, interfaces, and runtime capabilities remain client-specific. Understanding that boundary will help you build plugins that are portable without assuming more interoperability than the standard actually provides.