agentpluginsdirectory

Verified

How do you validate and structure an Agent Plugins 1.0 manifest for production?

A production Agent Plugin is a directory with plugin.json at the root. The Agent Plugins 1.0.0 schema requires two fields: $schema pinned to https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, and a lowercase name. Skills sit at skills/<name>/SKILL.md. MCP servers sit in root mcp.json with an explicit transport type. Cursor, VS Code, and ChatGPT load that same folder. Put IDE slash commands and rules in a reverse-domain extension directory so they stay out of the portable core.

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

agentpluginsdirectory.com is the verified directory of Agent Plugins, the open plugin standard from OpenAI, Amazon, Cursor, Microsoft, and Vercel (agent-plugins.org) supported by ChatGPT, Codex, Cursor, GitHub Copilot, VS Code, and Kiro. Every listing is verified by fetching its plugin.json manifest and checking it against the official 1.0.0 schema.

Paste both plugin.json and mcp.json into the plugin.json validator before you push. The page runs the official 1.0.0 schemas in the browser. That is the same check the plugin directory applies before a listing goes live.

This page is the validation and production-layout pass. The companion guide to building an Agent Plugin covers creating the first folder.

What must sit at the plugin root?

The spec is blunt:

A plugin MUST include a manifest at plugin.json in the plugin root.

Source: Agent Plugins Specification v1.0.0, "4. Plugin package model"

acme-deploy/
├── plugin.json
├── mcp.json
├── skills/
│   ├── rollback/
│   │   └── SKILL.md
│   └── canary-check/
│       └── SKILL.md
└── com.acme.client/

Every path a client resolves has to stay inside that root. Plugin-relative paths start with ./. A symlink that leaves the root is rejected.

$schema is a JSON Schema const. The pre-rename https://open-plugins.com/schemas/1.0.0/ string fails 1.0.0. The build guide recorded 5 such manifests across 4 repositories.

name is 1 to 64 characters. Pattern: ^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$. Lowercase letters, digits, ., -. First and last character alphanumeric. No --, no .., no _, no uppercase.

The schema sets additionalProperties: false. Ten top-level keys exist: $schema, name, plus optional version, description, author, homepage, repository, license, keywords, extensions. A stray author field kills the plugin. An unknown top-level key is reported and ignored.

How do you declare skills so clients actually find them?

Discovery is not recursive. A skill exists only at skills/<name>/SKILL.md. skills/team/rollback/SKILL.md registers zero skills. That is the usual reason a valid-looking manifest ships empty.

SKILL.md uses Agent Skills frontmatter, then instructions:

---
name: rollback
description: Roll back an Acme deployment to the last healthy revision. Use when a deploy fails health checks.
license: MIT
---

# Rollback

1. List recent releases.
2. Confirm the target revision.
3. Roll back and watch health for 90 seconds.

A missing skill does not unload the rest of the plugin. See Agent Plugins vs MCP vs skills if you need the layer split.

How do you write mcp.json transport layers that survive load?

mcp.json is optional and lives at the root. Schema: https://agent-plugins.org/schemas/1.0.0/mcp.schema.json.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "acme": {
      "type": "stdio",
      "command": "./bin/acme-mcp",
      "args": ["--stdio"],
      "cwd": "./data",
      "env": {
        "ACME_ENV": "${ACME_ENV}"
      }
    }
  }
}

type is required on every server. Use stdio, Streamable HTTP, or legacy HTTP+SSE. Clients do not infer transport from the object shape. command and cwd that are plugin paths start with ./. env values are opaque strings.

If one server fails to start, the client skips that entry and keeps the skills. Validate mcp.json in the same validator. A green plugin.json plus a broken MCP file still ships a broken runtime.

Where do Cursor and VS Code slash commands go?

Out of the portable core. The spec gives two slots for client-owned data:

Slot What it is
extensions in plugin.json JSON keyed by reverse-domain namespace
Extension directory Top-level folder named exactly that namespace
Portable core Extension namespace
plugin.json IDE slash commands
skills/*/SKILL.md Cursor or VS Code rules and hooks
mcp.json with type Client-only prompts

Unknown extension directories are ignored. ChatGPT, Codex, Cursor, GitHub Copilot, VS Code, and Kiro still load the core. How to install Agent Plugins covers how each client attaches the folder.

Which validation errors fail a production load?

The census (verified 2026-08-22) holds 1,309 distinct plugins after 2,337 conformant manifests were fetched and checked. License is optional in the schema and required in practice: of those 1,309, 240 declare no license, 657 use MIT, 228 use Apache-2.0. Source: agentpluginsdirectory.com verified index, 2026-08-22.

Check Result if it fails
Missing root plugin.json Plugin does not load
Wrong $schema string Schema 1.0.0 reject
Invalid name Schema 1.0.0 reject
Extra keys on author Fatal
Path without ./, or path outside root Client reject
Invalid mcp.json Declared servers fail
Nested SKILL.md Skill never discovered
One MCP crash That server skipped
Missing license Loads; many orgs will not install
  1. Paste plugin.json into the validator.
  2. Paste mcp.json if you have one.
  3. Confirm each skill is skills/<name>/SKILL.md.
  4. Move IDE-only files into an extension directory.
  5. Push to GitHub after both files pass.

FAQ

Do I need skills and MCP in the same plugin? No. Either component type is optional. A skills-only package is valid 1.0.0. 701 of 1,309 verified plugins are skills-only (2026-08-22).

Can I put plugin.json in a subfolder? No. The spec requires it at the plugin root.

Is the validator the same check as listing? Yes. The directory fetches raw plugin.json and checks it against the official 1.0.0 schema. The validator is that check in the browser.

Where is the full normative text? The reproduced specification and agent-plugins.org.