What Is the Purpose of marketplace.json in the .claude-plugin Directory?

The marketplace.json file in the .claude-plugin directory serves as the central catalog descriptor for the Claude plugins ecosystem, defining marketplace identity, managing legacy name mappings, and powering automated validation and installation workflows.

The anthropics/claude-plugins-community repository uses this JSON file as the single source of truth for plugin discovery and distribution. Located at .claude-plugin/marketplace.json, it orchestrates how the Claude client discovers, validates, and installs community plugins through precise source metadata and version pinning.

Defines Marketplace Identity

At the top level, marketplace.json establishes the marketplace's logical identity within the Claude ecosystem. The name field on line 2 declares the marketplace identifier as "claude-community", while the owner field on line 4 specifies "Anthropic" as the responsible entity. These fields allow the Claude client to distinguish between official, community, and third-party plugin sources when resolving installation requests.

Manages Legacy Naming Conventions

The renames section within the JSON file maintains backward compatibility for plugins that have undergone identifier changes. For example, lines 7-10 map the legacy identifier "qodo-skills" to its current name "qodo". This mapping ensures that existing user configurations, documentation links, and automated scripts continue to function even after a plugin rebrands or reorganizes its repository structure.

Enumerates the Plugin Catalog

The plugins array contains the authoritative list of every plugin available through the community marketplace. Each entry in this array specifies:

• name — The short identifier used in Claude slash commands (e.g., 0x, qodo)
• description — A human-readable summary displayed in plugin browsers
• source — The precise repository location, including URL, Git subdirectory, or SHA commit hash (lines 16-20)
• homepage — An optional link to documentation or project websites

Because the source field includes specific SHA pinning, installations are reproducible and protected against upstream repository changes.

Powers Validation and Discovery Tools

The repository's continuous integration system depends on marketplace.json to verify ecosystem integrity. The workflow defined in .github/workflows/validate-plugins.yml triggers the validate-plugins action, which executes scripts like .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh to perform the following checks:

1. Verifies that every plugin definition is well-formed JSON
2. Confirms that referenced SHAs exist in the source repositories
3. Ensures marketplace metadata stays synchronized with actual plugin directories

These automated guarantees ensure that users cannot install broken or misconfigured plugins through the marketplace interface.

Supports Dynamic Plugin Installation

When a Claude user executes an installation command such as /install 0x, the client loads marketplace.json to resolve the request. The client searches the plugins array for a matching name entry, clones the referenced repository at the exact SHA specified in the source field, and registers the plugin locally. This dynamic resolution system allows the marketplace to expand without requiring client software updates.

Practical Implementation Examples

The following examples demonstrate how to interact with marketplace.json programmatically.

Loading the Plugin Catalog

Use Python to fetch and parse the marketplace descriptor:

import json
import urllib.request

# Load marketplace.json from the repository

url = "https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json"
with urllib.request.urlopen(url) as resp:
    data = json.load(resp)

# Print a friendly list of plugin names and descriptions

for plugin in data["plugins"]:
    print(f"- {plugin['name']}: {plugin['description']}")

Resolving Legacy Plugin Names

Implement the rename logic to handle deprecated identifiers:

def resolve_name(name, marketplace):
    # Apply any historic rename mapping

    return marketplace.get("renames", {}).get(name, name)

# Usage

name = resolve_name("qodo-skills", data)
print(name)   # → "qodo"

Automating Plugin Installation

Extract source URLs and SHAs for automated deployment scripts:

PLUGIN=$(curl -s https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json \
 | jq -r '.plugins[] | select(.name=="0x") | .source.url')
SHA=$(curl -s https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json \
 | jq -r '.plugins[] | select(.name=="0x") | .source.sha')

git clone "$PLUGIN" plugin-0x
cd plugin-0x
git checkout "$SHA"

# …run the plugin's install command…

Relationship to Individual Plugin Manifests

While marketplace.json serves as the master catalog, each plugin directory contains its own .claude-plugin/plugin.json file. This individual manifest describes plugin-specific entry points, required MCP tools, and local metadata. The marketplace file points to these directories via the source field, creating a two-level validation system where the catalog validates structure and the individual manifests validate runtime behavior.

Summary

• marketplace.json acts as the authoritative source of truth for the anthropics/claude-plugins-community ecosystem.
• It defines marketplace identity through the name and owner fields located at lines 2 and 4.
• The renames section (lines 7-10) ensures backward compatibility for deprecated plugin identifiers.
• The plugins array (lines 16-20) provides version-pinned source metadata for reproducible installations.
• The CI workflow at .github/workflows/validate-plugins.yml uses this file to verify plugin integrity automatically.
• Dynamic installation commands resolve against this catalog to clone exact SHAs without client updates.

Frequently Asked Questions

What is the exact file path for the marketplace configuration?

The marketplace configuration resides at .claude-plugin/marketplace.json in the root of the anthropics/claude-plugins-community repository. This location is hardcoded into the validation workflows and Claude client resolution logic.

How does the marketplace handle renamed or migrated plugins?

The renames section within marketplace.json maps legacy identifiers to current names. For instance, "qodo-skills" automatically resolves to "qodo", ensuring that existing user scripts and configurations remain functional after a plugin rebrands.

Which automated systems depend on marketplace.json?

The repository's validation pipeline defined in .github/workflows/validate-plugins.yml reads this file to verify that all plugin entries contain valid JSON, reachable repositories, and existing SHA commit hashes. Additionally, the Claude client consumes this file to resolve /install commands dynamically.

How does marketplace.json differ from individual plugin.json files?

While marketplace.json serves as the master catalog listing all available plugins for the community marketplace, each plugin subdirectory contains its own .claude-plugin/plugin.json that defines runtime-specific metadata such as entry points and required tools. The marketplace file points to the plugin directories, while the individual manifests describe how to execute the plugins.

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