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

> Explore the Claude Plugins Marketplace.json schema. Understand the complete field reference and validation rules for this crucial file to build and submit your Claude plugins effectively.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: api-reference
- Published: 2026-09-04

---

**The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) schema:

```json
[
  {
    "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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) and is assembled from individual [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh) or [`.github/actions/validate-plugins/scripts/30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) files from each plugin directory into the single [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.