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

The marketplace.json file serves as the authoritative central registry and single source of truth for all community-contributed Claude Code plugins, containing immutable metadata that powers discovery, installation, and security verification across the ecosystem.

The anthropics/claude-plugins-community repository hosts the official read-only mirror of Anthropic’s community plugin marketplace. At its core, the .claude-plugin/marketplace.json file defines every vetted plugin available for installation, bridging the gap between internal security review processes and end-user client functionality.

The Central Registry: Structure and Location

File Location and Schema

The marketplace.json file resides at .claude-plugin/marketplace.json in the repository root. This JSON file contains a structured array of plugin entries, where each object specifies the plugin name, source repository URL, and a pinned commit SHA. According to the repository structure, this standardized schema allows the Claude client to resolve plugin identifiers to specific, immutable code versions without ambiguity.

Immutable Version Pinning

Each entry in marketplace.json includes a pinned commit SHA rather than mutable branch or tag references. This pinning mechanism ensures that installations remain reproducible and protected against supply chain attacks. When a user installs a plugin from the community marketplace, the client retrieves the exact code version approved during Anthropic’s internal review process, not the latest potentially unvetted commit.

Validation Pipeline and Quality Assurance

Nightly Generation from Internal Review

The file functions as a read-only mirror regenerated nightly from Anthropic’s internal review pipeline. As noted in the repository documentation, this architecture ensures that only security-vetted plugins appear in the public registry while maintaining separation between internal development environments and the public-facing community repository.

CI Workflow Enforcement

The repository enforces strict structural and security invariants through automated GitHub Actions workflows. In .github/workflows/validate-plugins.yml, the CI pipeline validates marketplace.json against official schemas and enforces specific constraints:

• Alphabetical sorting of plugin entries
• Duplicate detection to prevent namespace collisions
• HTTPS-only repository URLs to ensure encrypted source retrieval

Additional security verification occurs via .github/actions/scan-plugins/action.yml, which scans changed marketplace entries for policy violations before merging, while .github/actions/validate-plugins/action.yml handles the core schema validation logic.

Client Integration and Installation Flow

When users interact with the Claude Code marketplace, the client reads marketplace.json to present available plugins and resolve installation requests. The registry enables the following workflow:

# Add the community marketplace to your Claude Code client

claude plugin marketplace add anthropics/claude-plugins-community

# List all available plugins (client reads marketplace.json)

claude plugin marketplace list

# Install a specific plugin with pinned version guarantees

claude plugin install quickdesign@claude-community

# Update all installed plugins to latest approved versions

claude plugin marketplace update

During installation, the client parses the registry to map plugin names (such as quickdesign) to their source repositories and specific commit SHAs defined in marketplace.json, then fetches the exact code revision specified.

Summary

• Centralized Registry: marketplace.json at .claude-plugin/marketplace.json acts as the single source of truth for community plugin metadata in the anthropics/claude-plugins-community repository.
• Security Through Immutability: Pinned commit SHAs ensure users install only the exact code versions vetted by Anthropic’s internal review process.
• Automated Validation: CI workflows in .github/workflows/validate-plugins.yml enforce schema compliance, sorting, duplicate detection, and HTTPS requirements.
• Client Integration: The Claude Code client relies on this file to resolve plugin names to repositories and versions during claude plugin install operations.

Frequently Asked Questions

Where is marketplace.json located in the Claude plugin repository?

The file is located at .claude-plugin/marketplace.json in the root of the anthropics/claude-plugins-community repository. This standardized path allows the Claude Code client to locate and parse the registry when users add the community marketplace source.

How does marketplace.json ensure plugin security?

The file implements security through immutable version pinning—each plugin entry references a specific commit SHA rather than a branch name. Combined with nightly regeneration from Anthropic’s internal review pipeline and automated CI validation in .github/workflows/validate-plugins.yml, this ensures only vetted, unaltered code reaches end users.

Can developers manually edit marketplace.json to add their plugins?

No. The repository operates as a read-only mirror regenerated nightly from Anthropic’s internal systems. Plugin submissions must undergo the official review pipeline rather than direct pull requests to marketplace.json, ensuring all entries pass security scanning via .github/actions/scan-plugins/action.yml before publication.

How often does the marketplace.json file update?

The file regenerates nightly from the internal review pipeline. This schedule ensures newly approved plugins appear within 24 hours of vetting while maintaining the repository’s read-only integrity and preventing unauthorized modifications.

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