Claude Plugins Marketplace.json Schema: Complete Field Reference and Validation Rules

The marketplace.json file is a canonical JSON array where each element represents a Claude plugin object containing required fields like id, name, description, and repo, along with optional fields such as mcp and metadata that enable advanced plugin capabilities.

The anthropics/claude-plugins-community repository maintains a centralized registry of community-built Claude plugins. The marketplace.json schema defines the strict structure that every plugin entry must follow to be indexed and validated by the automated CI pipeline. This manifest serves as the single source of truth for the plugin ecosystem.

Core Structure of the Marketplace.json File

Located at .claude-plugin/marketplace.json, this file functions as the canonical manifest listing every community-published Claude plugin. It is strictly a JSON array containing plugin objects, each adhering to a fixed shape that the validation workflow checks against.

Required Fields in the Schema

Every plugin object in the marketplace.json schema must include these properties:

• id – Unique identifier string, usually matching the plugin's folder name.
• name – Human-readable plugin name displayed in the Claude UI.
• description – Full markdown-compatible description of the plugin's capabilities.
• author – The individual or organization that published the plugin.
• license – SPDX-style license identifier (e.g., MIT, Apache-2.0).
• repo – URL to the source code repository (typically GitHub).
• url – Public URL where the plugin can be installed or referenced.
• version – Semantic version string (e.g., 1.2.3).
• icon – URL to an SVG or PNG icon representing the plugin.
• tags – Array of strings for search and categorization (e.g., ["seo", "database"]).
• commands – Array of objects defining slash-commands, each containing name and description.
• skills – Array of strings naming the Claude Skills bundled with the plugin.

Optional Fields for Advanced Features

Beyond the core requirements, the schema supports two optional properties:

• mcp – An object containing Model-Context-Protocol details that let the plugin expose custom MCP tools.
• metadata – A free-form object for additional key/value pairs that the plugin author wishes to expose.

Example Plugin Entry

The following structure illustrates a complete plugin object following the marketplace.json schema:

[
  {
    "id": "quickdesign",
    "name": "QuickDesign",
    "description": "AI‑assisted video‑design toolkit …",
    "author": "Anthropic",
    "license": "MIT",
    "repo": "https://github.com/anthropics/quickdesign",
    "url": "https://github.com/anthropics/quickdesign",
    "version": "0.9.4",
    "icon": "https://github.com/anthropics/quickdesign/raw/main/.claude-plugin/icon.svg",
    "tags": ["video", "design", "AI"],
    "commands": [
      { "name": "/quickdesign:render", "description": "Render a video from a script." }
    ],
    "skills": ["quickdesign"],
    "mcp": { "tool": "quickdesign", "schema": "…" }
  }
]

CI Validation and Schema Enforcement

The repository enforces strict schema compliance through automated workflows defined in .github/workflows/validate-plugins.yml. This CI pipeline prevents malformed entries from merging into the main branch by validating every pull request that touches plugin files.

The validation process executes two critical scripts:

1. .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh – Invokes the CLI validator for the full marketplace JSON structure.
2. .github/actions/validate-plugins/scripts/30-validate-cli-external.sh – Runs claude plugin validate against individual plugin manifests to enforce type checking and required field presence.

Any missing required field, type mismatch, or schema deviation will cause the CI check to fail, blocking the PR until the violation is corrected.

Summary

• The marketplace.json schema requires a JSON array containing plugin objects with twelve mandatory fields defining identity, attribution, and functionality.
• Two optional fields (mcp and metadata) support protocol extensions and custom author-defined data.
• Validation scripts in .github/actions/validate-plugins/scripts/ automatically enforce schema compliance during CI.
• The canonical manifest resides at .claude-plugin/marketplace.json and is assembled from individual plugin.json files during the build process.

Frequently Asked Questions

What happens if a required field is missing from marketplace.json?

The CI workflow will fail when executing .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh or .github/actions/validate-plugins/scripts/30-validate-cli-external.sh, preventing the pull request from being merged until the schema violation is resolved.

Can I add custom fields to the marketplace.json schema?

Yes, use the optional metadata object to store free-form key/value pairs. However, you cannot add new top-level required fields without modifying the validation logic in the repository's GitHub Actions workflow.

How is the marketplace.json file generated?

The CI workflow assembles individual plugin.json files from each plugin directory into the single .claude-plugin/marketplace.json manifest, then validates the assembled result against the schema rules before allowing the merge.

What license identifiers does the schema accept?

The license field expects SPDX-style identifiers such as MIT, Apache-2.0, or GPL-3.0, ensuring standardized license reporting across the Claude plugin ecosystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}