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

> Discover the crucial role of marketplace.json in the Claude plugin ecosystem. Learn how it powers discovery, secure installation, and automated validation for community plugins.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-08-31

---

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

The file resides at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md), this structure allows the Claude CLI to resolve plugin sources without requiring authors to ship complete [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifests for every release.

## How the CLI Consumes [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)

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

```bash

# 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) contents without runtime dependency on external services

As documented in the repository [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) (as seen in [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json)), the marketplace can synthesize minimal manifests when authors prefer simpler repository structures. A typical [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) entry appears as:

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json)** is the canonical, read‑only index of community Claude plugins located at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest?

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