What Is the Role of `marketplace.json` in the Claude Plugin Ecosystem?

The marketplace.json file serves as the canonical index of all community‑maintained Claude plugins, enabling discovery, secure installation, and automated validation within the Claude CLI ecosystem.

In the anthropics/claude-plugins-community repository, marketplace.json functions as the single source of truth that powers the entire plugin marketplace. This JSON catalogue enumerates every approved plugin, specifies exact source locations with cryptographic verification, and undergoes rigorous CI validation to maintain ecosystem integrity.

How marketplace.json Structures Plugin Discovery

The file resides at .claude-plugin/marketplace.json and contains a top‑level JSON object with a plugins array. Each entry defines:

• name — The plugin's unique identifier
• source repository — External Git repository hosting the plugin code
• pinned SHA — Exact commit hash for reproducible, tamper‑resistant installation
• optional metadata — Description, icon URL, and minimum Claude version requirements

According to the repository's README.md, this structure allows the Claude CLI to resolve plugin sources without requiring authors to ship complete plugin.json manifests for every release.

How the CLI Consumes marketplace.json

The Claude CLI commands interact directly with this marketplace file to manage plugins:

# Register the community marketplace in your local Claude configuration

claude plugin marketplace add anthropics/claude-plugins-community

# Display all available plugins from the registered marketplace

claude plugin marketplace list

# Install a specific plugin by its marketplace name

claude plugin install quickdesign/quickdesign-cli

# Update all marketplace plugins to their latest approved SHAs

claude plugin marketplace update

When you run claude plugin marketplace add, the CLI loads .claude-plugin/marketplace.json and treats its entries as installable artifacts. The resolution process:

1. Fetches the source repository at the exact pinned SHA
2. Verifies the commit hash matches the marketplace entry
3. Synthesizes a minimal plugin.json manifest if the author didn't provide one
4. Copies validated plugin code into ~/.claude/plugins/

This SHA‑pinning mechanism ensures that installing quickdesign/quickdesign-cli today produces bit‑for‑bit identical code tomorrow, protecting against supply‑chain attacks and unexpected breaking changes.

Automated Validation via GitHub Actions

The marketplace file is validated on every pull request through .github/workflows/validate-plugins.yml. This workflow enforces critical invariants:

• Schema compliance — Runs claude plugin validate marketplace.json against Anthropic's official schema
• Alphabetical ordering — Maintains deterministic, diff‑friendly file structure
• Duplicate detection — Prevents namespace collisions
• SHA‑pin requirement — Rejects entries lacking explicit commit hashes
• HTTPS‑only enforcement — Blocks insecure transport protocols

The validation script at .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh invokes the CLI validator, ensuring that malicious or malformed entries never reach the canonical marketplace file.

Nightly Synchronization and Auditing

marketplace.json is synced nightly from Anthropic's internal review pipeline. This architecture provides two key benefits:

• Static auditability — The file remains version‑controlled in Git, enabling complete historical analysis of plugin additions, removals, and SHA updates
• Offline reliability — Users can reference marketplace.json contents without runtime dependency on external services

As documented in the repository README.md, this design prioritizes security and transparency over real‑time dynamism—every plugin in the marketplace has passed internal review before appearing in the public index.

Example Plugin Entry Structure

While individual plugins may include their own .claude-plugin/plugin.json (as seen in tres-finance-plugin/.claude-plugin/plugin.json), the marketplace can synthesize minimal manifests when authors prefer simpler repository structures. A typical marketplace.json entry appears as:

{
  "plugins": [
    {
      "name": "quickdesign/quickdesign-cli",
      "repository": "https://github.com/quickdesign/quickdesign-cli",
      "sha": "a1b2c3d4e5f6789abcdef1234567890abcdef12",
      "description": "Generate design tokens from natural language",
      "icon": "https://example.com/icon.png",
      "minClaudeVersion": "1.5.0"
    }
  ]
}

Summary

• marketplace.json is the canonical, read‑only index of community Claude plugins located at .claude-plugin/marketplace.json
• The file enables secure, reproducible installation via SHA‑pinned repository references
• CLI commands (marketplace add, list, install, update) consume this file to resolve and fetch plugins
• GitHub Actions validation in .github/workflows/validate-plugins.yml enforces schema compliance and security invariants on every PR
• Nightly synchronization from Anthropic's internal pipeline ensures the marketplace reflects approved plugins while maintaining static auditability

Frequently Asked Questions

What happens if a plugin author updates their repository after SHA pinning?

The marketplace entry retains the original pinned SHA, so existing installations remain unchanged. Anthropic's nightly sync process updates the SHA in marketplace.json only after re‑review, at which point users can run claude plugin marketplace update to receive the new version.

Can I use a custom marketplace.json file outside the official repository?

Yes. The claude plugin marketplace add <repo> command accepts any repository containing a valid .claude-plugin/marketplace.json file, allowing organizations to maintain private plugin registries with the same validation and resolution semantics.

Why does the marketplace require HTTPS URLs and SHA pins?

These requirements mitigate supply‑chain attack vectors: HTTPS prevents man‑in‑the‑middle interception during plugin fetch, while SHA pins guarantee that the code executed matches exactly what was reviewed, regardless of subsequent changes to the source repository's default branch.

How does the CLI handle plugins without a native plugin.json manifest?

The marketplace resolution synthesizes a minimal plugin.json from the entry metadata—using the provided name, description, and inferred execution parameters—so plugin authors can distribute tools with zero boilerplate configuration files.

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