Understanding marketplace.json Renames and Source Types in Claude Code

The marketplace.json manifest in the anthropics/claude-plugins-community repository drives plugin discovery through three core sections: a renames map for backward compatibility, a plugins array for metadata, and source objects that declare whether to fetch code via direct URL or subdirectory extraction.

The marketplace.json file serves as the single source of truth for the Claude Code community plugin ecosystem. Located at .claude-plugin/marketplace.json in the repository root, this JSON manifest dictates how the marketplace resolver locates, validates, and installs community-contributed plugins while maintaining strict reproducibility and backward compatibility.

The Structure of marketplace.json

The manifest organizes plugin metadata into three distinct sections that work together to resolve installation requests.

The Renames Map (Backward Compatibility)

The renames object at the top of the file provides transparent aliases for plugins that have changed identifiers. When a user references an outdated plugin name, the resolver consults lines 6–11 of marketplace.json to map legacy names to current canonical identifiers.

For example, requesting qodo-skills automatically resolves to qodo because the renames map contains that specific alias definition. This prevents breaking existing workflows when maintainers reorganize plugin naming conventions.

The Plugins Array

The plugins array contains structured metadata for every available community plugin. Each entry includes the plugin name, description, author information, and critically, a nested source object that instructs the resolver exactly how to retrieve the code.

Source Objects: url vs git-subdir

Every plugin entry contains a source object with a source.type field that must be either "url" or "git-subdir". These types determine the fetch strategy:

• url – Indicates the plugin resides at the root of a dedicated Git repository. The manifest provides the clone URL and a fixed SHA for reproducible installation.
• git-subdir – Indicates the plugin lives within a subdirectory of a larger repository, enabling monorepo architectures where multiple plugins share a single codebase.

How the Resolver Processes Plugin Requests

The marketplace resolver follows a strict three-phase pipeline when handling installation commands like claude plugin marketplace add <name>.

First, during Name Lookup, the resolver checks if the requested identifier exists in the plugins array. If not found, it queries the renames object at lines 6–8 to check for legacy aliases. For instance, qodo-skills maps to qodo before the search proceeds.

Second, in Plugin Entry Retrieval, the resolver locates the matching entry in the plugins array and extracts the nested source configuration.

Third, during Source Resolution, the source.type value triggers specific fetch logic. For url sources like the 0x plugin (defined at lines 16–20), the resolver executes git clone directly on the repository URL and checks out the exact SHA (0167bbb411cc972b966127d23c23de801061fa99). For git-subdir sources like a11y-fixer (lines 78–84), the resolver clones the parent repository, checks out the specified reference, then extracts only the subdirectory defined in the path field.

Source Type Deep Dive

Each source type serves distinct repository architectures while maintaining immutable installation guarantees.

URL Source (Root-Level Repositories)

The url source type supports standalone plugin repositories. The manifest entry specifies:

{
  "source": {
    "source": "url",
    "url": "https://github.com/0xProject/0x-ai.git",
    "sha": "0167bbb411cc972b966127d23c23de801061fa99"
  }
}

This configuration guarantees that every installation pulls the exact commit 0167bbb411cc972b966127d23c23de801061fa99, preventing supply-chain attacks from upstream repository changes.

Git-Subdir Source (Monorepo Support)

The git-subdir type enables granular extraction from shared repositories:

{
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/barnburner121/claude-plugin-marketplace.git",
    "ref": "main",
    "sha": "abc123...",
    "path": "generated-plugins/a11y-fixer"
  }
}

As implemented in the a11y-fixer entry at lines 78–84, this structure allows the marketplace to host multiple plugins within a single repository while installing only the relevant subdirectory.

Security and Reproducibility Benefits

Pinning each plugin to a specific SHA prevents "moving target" vulnerabilities where malicious code could replace legitimate plugin versions. The renames map further ensures stability by allowing maintainers to restructure plugin identifiers without breaking existing user configurations that reference legacy names.

Practical Implementation Examples

The following JavaScript demonstrates how to programmatically resolve a plugin using the marketplace manifest structure:

// Resolve a plugin request using the marketplace manifest
async function resolvePlugin(name) {
  const manifest = await fetch(
    "https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json"
  ).then(r => r.json());

  // Apply renames if needed
  const canonicalName = manifest.renames?.[name] ?? name;

  const entry = manifest.plugins.find(p => p.name === canonicalName);
  if (!entry) throw new Error(`Plugin ${name} not found`);

  const src = entry.source;
  if (src.source === "url") {
    // Clone repo at src.url and checkout src.sha
    return `git clone ${src.url} && git checkout ${src.sha}`;
  } else if (src.source === "git-subdir") {
    // Clone repo, checkout src.ref, then use src.path
    return `git clone ${src.url} && git checkout ${src.ref} && cd ${src.path}`;
  }
}

Command-line installation examples illustrate the underlying resolver behavior:

# Installing the `a11y-fixer` plugin (git-subdir source)

$ claude plugin marketplace add a11y-fixer

# Internally the resolver runs (simplified):

git clone https://github.com/barnburner121/claude-plugin-marketplace.git
git checkout main
cd generated-plugins/a11y-fixer

# Installing the `0x` plugin (url source)

$ claude plugin marketplace add 0x

# Internally the resolver runs:

git clone https://github.com/0xProject/0x-ai.git
git checkout 0167bbb411cc972b966127d23c23de801061fa99

Summary

• marketplace.json serves as the central manifest at .claude-plugin/marketplace.json in the anthropics/claude-plugins-community repository.
• The renames map at lines 6–11 provides backward-compatible aliases (e.g., qodo-skills → qodo) to prevent workflow breakage.
• source.type values (url or git-subdir) determine whether the resolver clones a standalone repository or extracts a subdirectory from a monorepo.
• SHA pinning in source configurations guarantees reproducible builds and protects against supply-chain attacks.
• The owner-baseline.json file tracks GitHub account IDs for repository owners to support marketplace maintenance workflows.

Frequently Asked Questions

What happens if I request a plugin by its old name after it has been renamed?

The marketplace resolver automatically checks the renames object in marketplace.json before searching the plugins array. If your requested name matches a key in the renames map (such as qodo-skills mapping to qodo), the resolver transparently substitutes the canonical name and proceeds with installation. This ensures backward compatibility without requiring users to update their scripts or configurations.

How does the git-subdir source type differ from the url source type?

The url source type expects the plugin to exist at the root of its own Git repository, cloning the entire repo and checking out a specific SHA. The git-subdir type supports monorepos by cloning the parent repository, checking out a reference branch or tag, then extracting only the specified subdirectory path. This allows multiple plugins to coexist in a single repository while maintaining independent versioning through SHA pinning.

Why does marketplace.json use SHA pinning instead of branch references?

SHA pinning guarantees immutable installations by referencing exact commit hashes rather than moving branch pointers. This prevents supply-chain attacks where a compromised repository could inject malicious code into what appears to be a stable release. Both url and git-subdir source types require a sha field to ensure that every installation of a specific plugin version retrieves identical code, regardless of when the installation occurs.

Where does the marketplace store information about plugin repository owners?

Repository ownership metadata is tracked in .github/owner-baseline.json, which maps GitHub account IDs to repository owners. This file supports the marketplace maintenance workflows by providing a baseline for verifying repository ownership changes and ensuring that only authorized maintainers can update plugin entries in the community marketplace.

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