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

> Discover the .claude-plugin/marketplace.json file, the core manifest for Claude's plugin registry. Learn how it powers discovery, installation, and verification for community plugins.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-05

---

**The [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) is to serve as the **central plugin registry** for the Claude Plugins Community repository. Located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md), the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) file explicitly states that contributors should not modify [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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:**

```bash
claude plugin marketplace add anthropics/claude-plugins-community

```

This command fetches [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) and registers the `claude-community` owner in the local CLI configuration.

**Install a specific plugin:**

```bash
claude plugin install 0x@claude-community

```

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

```bash
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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) workflow treats [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) | Master manifest containing all plugin metadata and renames map |
| [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) | Usage documentation explaining marketplace mechanics |
| [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) | CI workflow for manifest validation |
| [`.github/actions/validate-plugins/action.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/action.yml) | Reusable GitHub Action for validation logic |

## Summary

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