plugin.json Schema Reference

Two contracts, not one field allowlist

A plugin manifest belongs at .claude-plugin/plugin.json under the plugin root. Native Claude Code supports more than eight properties, including component paths and runtime configuration. Its current manifest documentation makes name the required field when a manifest is supplied; some native plugin layouts can omit the manifest entirely.

That permissive runtime floor is not this marketplace’s publication contract. The pinned kernel’s authoring/v1 marketplace envelope requires name, version, description, author, homepage, license, keywords, and commands. Additional supported fields remain possible. The repository’s authoritative validator and advisory kernel lanes have distinct roles; see STANDARDS.md.

Use the current native manifest reference, the pinned kernel schema, and the repository validator instead of treating this page as a second schema authority.

Marketplace manifest example

The following is a complete metadata envelope for an illustrative instruction plugin with no command files. URLs and identity are examples to replace with the author’s actual public project information:

{
  "name": "example-review",
  "version": "1.0.0",
  "description": "Review a selected configuration and produce a bounded, evidence-linked report.",
  "author": { "name": "Example Maintainer" },
  "homepage": "https://example.com/example-review",
  "repository": "https://github.com/example/example-review",
  "license": "MIT",
  "keywords": ["configuration", "review"],
  "commands": []
}

For a command file, use a path such as ./commands/review.md in commands and keep the file inside the plugin. Path forms and default discovery rules differ by component; consult the native reference rather than guessing from one example.

Other native fields

Claude Code also documents fields such as displayName, skills, agents, hooks, mcpServers, lspServers, dependencies, userConfig, metadata, and other supported extension surfaces. Whether a field is usable depends on its exact documented shape and the runtime version.

Do not add npm’s scripts or main to the plugin manifest to create a runtime build. Put Node package metadata in package.json, and declare the actual server command in MCP configuration.

An unrecognized field produces a warning in the repository’s default manifest check; --strict promotes that warning to an error. Missing native name and wrong field types remain errors. A native validator’s warning about optional metadata is different from a marketplace envelope failure.

Ownership and generated files

The plugin manifest describes the artifact. The editable .claude-plugin/marketplace.extended.json describes the marketplace listing and its source path. marketplace.json, catalog projections, generated package manifests, and the README catalog section are derived; use their canonical generators.

Pure external mirrors are upstream-owned. Submit fixes upstream and use the reviewed source-specific sync path; do not patch their manifests locally to pass a gate.

Version namespaces

Do not assume npm package and plugin display versions must be identical. The approved repository formula moves display surfaces by MINOR and the npm surface by PATCH for routine updates. Follow blueprint 727 V1 and the current auto-bump implementation. Do not manually promote an npm minor or skip automation to make strings match.

Validate each relevant layer

From the repository root, replacing the illustrative path:

claude plugin validate ./plugins/category/example-review
python3 scripts/validate-skills-schema.py --marketplace --verbose plugins/category/example-review/

The companion ccpi validate is a useful local check, but does not implement every native manifest or marketplace kernel requirement. A JSON parse alone proves neither runtime support nor safe behavior.

MCP and other runtime plugins

An MCP plugin uses the same manifest concept, plus an actual server configuration and runtime artifacts. The protocol is language-independent. When the command is node, a JavaScript argument need not be directly executable; a directly executed script needs its own interpreter/shebang and permissions. In both cases the clean installation must contain the entry point and required dependencies.

Use an absolute plugin-relative entry in the server argument:

{
  "mcpServers": {
    "example-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"]
    }
  }
}

This is a native stdio configuration excerpt, not proof of marketplace prescreen compliance or a successful server launch. Do not add unsupported runtime fields merely to satisfy a tracking overlay; review the relevant owner contract separately.

Common failures