How to Build an Agent Plugin 1.0 for AI Coding Tools

Agent Plugins 1.0 has nine compatible client entries, two portable component types, and one required manifest. That is either refreshingly small or suspiciously small, depending on how many plugin standards you have survived. If you are searching for how to build an Agent Plugin 1.0, the useful answer starts with that constraint: package the common core once, then test every host you claim to support.

The standard was published on August 6, 2026. On August 12, GitHub announced support across VS Code, Copilot CLI, the Copilot SDK, and the Copilot app. The practical win is narrower than one identical agent everywhere: one portable release-notes skill, one optional MCP declaration, and fewer vendor-shaped copies to maintain.

What Agent Plugins 1.0 actually standardizes

An Agent Plugin is a directory with a root plugin.json. Version 1.0 defines two portable components beneath it: Agent Skills in skills/ and MCP server declarations in mcp.json. The current compatibility matrix lists VS Code, Cursor, GitHub Copilot, ChatGPT and Codex, Kiro, Hermes Agent, OpenClaw, Grok Bot, and NanoClaw.

Portable in 1.0	Still client-specific
Plugin identity and version	Installation and updates
Agent Skills	Permissions and user interface
MCP server declarations	Hooks, commands, agents, and rules
Extension namespace mechanism	Authentication and secret storage

That split is the whole design. The standard removes duplicate packaging for instructions and tools; it does not make every agent behave identically. A portable plugin is closer to a universal shipping container than a universal vehicle. The box fits. The controls remain gloriously vendor-shaped.

The small core also limits failure. One malformed skill can be skipped while other skills and MCP entries continue loading. A broken individual MCP server disables that entry rather than the entire package. An invalid top-level mcp.json, however, disables the plugin’s MCP component. That gives you a useful debugging order: validate the manifest, validate each component document, then test behavior.

How to build an Agent Plugin 1.0 from two files

Start with a skill-only package. The canonical build guide confirms that plugin.json plus one SKILL.md is enough for a useful plugin. Our example asks an agent to turn repository evidence into release notes:

release-checks/
├── plugin.json
└── skills/
    └── release-checks/
        └── SKILL.md

Create the manifest

Place this plugin.json at the package root:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-checks",
  "version": "1.0.0",
  "description": "Draft evidence-backed release notes from repository changes.",
  "license": "MIT",
  "keywords": ["release-notes", "quality"]
}

The schema is closed. Do not paste hooks, agents, commands, or mcpServers into the top level because another vendor once put them there. Plugin names must use lowercase letters, numbers, hyphens, or periods, start and end with an alphanumeric character, and avoid doubled hyphens or periods.

Notice what the manifest does not contain: a list of skills. A compatible client discovers immediate folders under skills/ automatically. Keeping component paths out of the manifest makes the package boring in the best way—you can add a second valid skill without editing a central registry and creating one more place for a typo to win.

Write the portable skill

Create skills/release-checks/SKILL.md:

---
name: release-checks
description: Use when asked to audit a release candidate or draft release notes.
---

# Release checks

1. Inspect the repository's changes since the previous release tag.
2. Separate user-facing changes, fixes, breaking changes, and internal work.
3. Cite the commit, pull request, test, or file that supports each claim.
4. Flag claims that the repository evidence cannot verify.
5. Draft concise release notes. Do not invent benefits or benchmark results.

The skill directory and frontmatter name should match, and the filename must be exactly SKILL.md. Clients inspect only immediate children of skills/; they do not spelunk through arbitrary nested folders hoping to discover your intentions.

The description is operational metadata, not brochure copy. State when the skill should load. The body should define evidence, output, and stop conditions—the same principle behind giving coding agents durable project context instead of making them reverse-engineer policy from a tasteful README.

Add mcp.json only when instructions are not enough

A skill tells an agent how to work. MCP gives it executable tools or external data. If release checks only need repository access already provided by the host, stop at the skill. Add mcp.json when you actually own a validator, deployment service, or reporting system the agent must call.

The portable MCP rules support stdio, Streamable HTTP, and deprecated legacy SSE. This template assumes your package includes a real executable at bin/release-checks:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "release-checks": {
      "type": "stdio",
      "command": "./bin/release-checks",
      "args": ["--state", "${PLUGIN_DATA}/release-checks"],
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

The command field is one executable token, not a shell command, and placeholders do not expand inside it. They do expand in arguments, environment values, and the working directory. Use PLUGIN_DATA for writable state that should survive updates; use PLUGIN_ROOT for packaged files. Version 1.0 defines no portable OAuth or credential-reference field, so never bake secrets into literal HTTP headers.

Choose the transport deliberately. Stdio suits a bundled local process; Streamable HTTP suits a remote service with a stable HTTPS endpoint. Legacy SSE exists for compatibility, but support is optional and the transport is deprecated. Each server entry declares one transport, and the standard defines no automatic fallback when that connection fails. Extra server entries are not resilience by themselves; they are extra configurations to test.

If one package is becoming a small MCP zoo, a managed MCP gateway may be the cleaner control plane. Portability is not permission to hide six daemons behind one friendly manifest.

Validate and test the plugin without trusting vibes

The $schema field lets a capable editor flag invalid names and misplaced fields. Also perform a plain JSON syntax check—but remember that valid JSON is not the same as a conforming plugin. jq can catch a missing comma; it cannot tell you that a vendor-specific field wandered into the portable manifest.

jq empty plugin.json
# If you added MCP:
jq empty mcp.json

• Check discovery: SKILL.md is an immediate child under skills/release-checks/.
• Check identity: the folder and frontmatter both say release-checks.
• Check behavior: invoke the skill on a repository with known changes and look for evidence, not polished guesses.
• Check failure: remove a required fact and confirm the skill flags the gap instead of completing the story itself.

For one concrete host test, the VS Code instructions let you register a local directory in settings:

{
  "chat.plugins.enabled": true,
  "chat.pluginLocations": {
    "/absolute/path/to/release-checks": true
  }
}

Confirm the skill appears in Configure Skills, then run the behavior checks above. That settings key is VS Code-specific. Repeat discovery, permission, and execution tests in every client you advertise because the standard packages components; it does not certify the host around them.

Test restraint as seriously as output quality. Give the skill an ordinary bug-fix request and confirm it does not force a release-note workflow into the conversation. Then give it ambiguous release evidence and check that it asks or flags uncertainty. A skill that triggers constantly is not reusable expertise; it is a colleague who joins every meeting because one agenda once contained the word “release.”

The portability boundary is also the security boundary

Client extensions preserve features that version 1.0 does not standardize. Copilot-specific hooks, commands, rules, and agents can live under com.github.copilot/; other clients ignore that namespace and still load the portable core. Migrate additively: introduce the common manifest, skills, and MCP declarations first, keep working vendor files, test each host, and retire duplication only after the results agree.

Review the package as code, because some of it is code. Hooks can run shell commands, MCP servers can start processes, and broader compatibility can widen a compromised plugin’s reach. Use the publisher, path, executable, network destination, and requested credentials as review inputs, then apply the isolation and permission controls in our six-layer agent security checklist.

The unanswered question is whether vendors will keep extension namespaces thin or rebuild incompatible plugin stacks around the shared center. Agent Plugins 1.0 does not make every agent the same; it gives the parts that should be boring one dependable address. The 1.1.0 working draft is the next concrete checkpoint: watch whether it adds another portable component or keeps the common center deliberately small.