What Is .claude-plugin/marketplace.json? The Complete Guide to Claude's Plugin Registry

The .claude-plugin/marketplace.json file is the canonical manifest that powers discovery, installation, and verification of all community plugins in the Claude Plugins Community repository.

This JSON file sits at the heart of Anthropic's plugin ecosystem, acting as the machine-readable source of truth that the Claude CLI uses to resolve, download, and validate community-contributed plugins. Whether you're installing a plugin or submitting one for review, understanding this manifest is essential for working with Claude's extensibility model.

Central Plugin Registry

The primary purpose of .claude-plugin/marketplace.json is to serve as the central plugin registry for the Claude Plugins Community repository. Located at .claude-plugin/marketplace.json in the repository root, this file enumerates every vetted community plugin available for installation.

Each entry in the registry contains critical metadata:

• Plugin name — The unique identifier used in CLI commands
• Description — Human-readable summary of functionality
• Source location — Git URL or subdirectory path where the plugin code resides
• SHA — Pinned commit hash ensuring reproducible builds
• Homepage — Link to documentation or project page

This structured format enables the Claude CLI to automatically resolve dependencies and verify plugin integrity during installation.

Read-Only Mirror Architecture

The repository operates as a read-only mirror of Anthropic's internal marketplace. As documented in README.md, the marketplace.json file regenerates nightly from Anthropic's internal review pipeline — not through direct community edits.

This architecture ensures:

• Only security-reviewed plugins appear in the public registry
• The manifest maintains consistency with Anthropic's quality standards
• Community PRs cannot bypass the internal vetting process

The README.md file explicitly states that contributors should not modify .claude-plugin/marketplace.json directly, as the internal pipeline overwrites any changes during the nightly sync.

Installation Entry-Point for Claude CLI

The manifest functions as the installation entry-point when users interact with the Claude CLI. Two primary commands leverage this file:

Register the community marketplace:

claude plugin marketplace add anthropics/claude-plugins-community

This command fetches .claude-plugin/marketplace.json and registers the claude-community owner in the local CLI configuration.

Install a specific plugin:

claude plugin install 0x@claude-community

The CLI parses marketplace.json to locate the "0x" plugin, retrieves its pinned SHA and source URL, and performs the installation. Without this manifest, the CLI cannot resolve which code to fetch or which version to use.

Backward Compatibility via Renames

The top-level renames map in .claude-plugin/marketplace.json handles legacy plugin identifiers that have been renamed. This guarantees backward compatibility for existing workflows and scripts.

For example, if a plugin originally named wordpress-com was renamed to build-with-wordpress, the renames map transparently redirects:

claude plugin install wordpress-com@claude-community  # Automatically maps to build-with-wordpress

This mechanism prevents breaking changes when plugin maintainers rebrand or reorganize their projects.

Validation and CI Integration

The .github/workflows/validate-plugins.yml workflow treats .claude-plugin/marketplace.json as the source of truth for all marketplace operations. The CI pipeline performs:

• Schema validation — Ensures JSON structure conforms to expected format
• Integrity checks — Verifies all referenced SHAs and URLs are reachable
• PR gating — Blocks releases if the manifest fails validation

The companion action at .github/actions/validate-plugins/action.yml defines the reusable validation logic used across Anthropic's plugin infrastructure.

Because the file regenerates from internal pipelines, CI primarily validates that the generated manifest is well-formed and consistent, rather than accepting manual edits.

File Structure and Location

File Path	Purpose
.claude-plugin/marketplace.json	Master manifest containing all plugin metadata and renames map
README.md	Usage documentation explaining marketplace mechanics
.github/workflows/validate-plugins.yml	CI workflow for manifest validation
.github/actions/validate-plugins/action.yml	Reusable GitHub Action for validation logic

Summary

• .claude-plugin/marketplace.json is the authoritative registry for Claude community plugins, located at the repository root
• It operates as a read-only mirror regenerated nightly from Anthropic's internal review pipeline
• The Claude CLI uses it as the installation entry-point for the claude plugin command family
• The renames map ensures backward compatibility when plugin identifiers change
• CI validation in .github/workflows/validate-plugins.yml enforces manifest integrity before any release

Frequently Asked Questions

Can I edit .claude-plugin/marketplace.json directly in a pull request?

No. The file regenerates automatically from Anthropic's internal marketplace pipeline. Direct edits in PRs are overwritten during the nightly sync. To add or modify a plugin, follow the submission process described in the repository's contribution guidelines.

How does the Claude CLI know which plugin version to install?

The manifest pins each plugin to a specific SHA in its source repository. When you run claude plugin install, the CLI reads this SHA from marketplace.json and fetches exactly that revision, ensuring reproducible builds and preventing unexpected changes from upstream updates.

What happens if I try to install a renamed plugin?

The renames map in .claude-plugin/marketplace.json transparently redirects old identifiers to current ones. Your installation succeeds without requiring you to update your scripts or learn the new plugin name.

Where does the actual plugin code come from?

Each entry in marketplace.json specifies a source URL and optional subdirectory path. The CLI clones or downloads from that location, not from the claude-plugins-community repository itself, which only hosts the manifest and related tooling.

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