How Plugins Are Sourced in Claude Plugins Community: The Marketplace Manifest Explained

Claude Plugins Community sources plugins through a centralized marketplace manifest at .claude-plugin/marketplace.json that enumerates each plugin's code location using either direct Git URLs or subdirectory references, with every entry pinned to specific commit SHAs for reproducible installations.

The Claude Plugins Community repository maintains a structured approach to plugin distribution through a central registry system. Understanding how plugins are sourced in Claude Plugins Community requires examining the manifest-based architecture that defines where plugin code lives and how Claude Code retrieves and validates it. This guide breaks down the technical implementation using actual source files from the anthropics/claude-plugins-community repository.

The Central Marketplace Manifest

At the root of the repository, .claude-plugin/marketplace.json serves as the single source of truth for all published plugins. This JSON file enumerates every available plugin through individual entries that include metadata and a critical source block. According to the source code at line 13-20 of the marketplace manifest, each entry describes the plugin's name, description, and sourcing instructions that tell Claude Code exactly where to fetch the plugin's code and which commit to checkout.

Supported Source Types

The manifest supports two distinct methods for locating plugin code, each defined by the source field within the entry's source object.

Direct URL Source (url type)

This source type is used when a plugin resides at the root of a Git repository. The method requires two fields:

• url: The direct Git URL pointing to the repository
• sha: The exact commit hash that must be checked out

This approach is implemented for plugins like "0x", where the source block specifies https://github.com/0xProject/0x-ai.git pinned to commit 0167bbb411cc972b966127d23c23de801061fa99 as documented in the marketplace manifest at lines 15-20.

Git Subdirectory Source (git-subdir type)

This source type accommodates plugins that live within subdirectories of larger repositories. The method requires:

• url: The Git URL for the parent repository
• path: The subdirectory path where the plugin code resides
• ref: The branch or tag to checkout
• sha (optional): An exact commit hash for additional pinning

This structure allows community members to maintain multiple plugins within a single monorepo while allowing Claude Code to extract only the relevant subdirectory during installation.

The Plugin Sourcing Workflow

When a user initiates plugin installation, Claude Code executes a five-step resolution process:

1. Read the marketplace manifest – The system parses .claude-plugin/marketplace.json located at the repository root to retrieve the complete plugin catalog.

2. Select the plugin entry – Claude Code locates the target plugin by name and extracts its source block, which contains the type-specific fetch instructions.

3. Clone the repository – Using the provided URL, the system clones the repository and checks out the specified sha or ref. For git-subdir sources, it extracts only the files within the defined path.

4. Load the plugin descriptor – Inside the fetched code, Claude Code searches for .claude-plugin/plugin.json to obtain the plugin's metadata, version, author information, and configuration requirements. For example, the TRES Finance plugin descriptor at tres-finance-plugin/.claude-plugin/plugin.json lines 19-26 declares a required DeBank API key in its userConfig section.

5. Register the plugin – The system registers the plugin under its namespace (such as 0x or tres-finance-plugin) and makes its skills available as slash commands within Claude Code.

Plugin Descriptor and Configuration

After sourcing the code, Claude Code validates the plugin through its descriptor file. This file contains:

• Metadata: Name, version, description, and author details
• User configuration: Required secrets or settings defined in userConfig
• Runtime instructions: Entry points and available commands

The TRES Finance implementation demonstrates this structure, requiring users to provide a DEBANK_API_KEY marked as sensitive in the configuration schema.

Code Implementation Examples

Below is the pseudo-code logic Claude Code uses to resolve plugin sources based on the manifest:

def fetch_plugin(entry):
    src = entry["source"]
    if src["source"] == "url":
        git_clone(src["url"], sha=src["sha"])
    elif src["source"] == "git-subdir":
        git_clone(src["url"], ref=src["ref"])
        extract_subdir(src["path"])
    # Load the plugin descriptor

    descriptor = read_json(".claude-plugin/plugin.json")
    register_plugin(descriptor)

Example entry for the "0x" plugin from the marketplace manifest:

{
  "name": "0x",
  "description": "Guide developers through swapping ERC-20 tokens using the 0x API …",
  "source": {
    "source": "url",
    "url": "https://github.com/0xProject/0x-ai.git",
    "sha": "0167bbb411cc972b966127d23c23de801061fa99"
  },
  "homepage": "https://github.com/0xProject/0x-ai"
}

Example plugin descriptor showing configuration requirements:

{
  "name": "tres-finance-plugin",
  "description": "The first official TRES Finance plugin for Claude Code …",
  "version": "1.12.1",
  "userConfig": {
    "DEBANK_API_KEY": {
      "title": "DeBank API Key",
      "description": "Your DeBank Pro API key …",
      "type": "string",
      "sensitive": true
    }
  }
}

Key Source Files

The sourcing mechanism relies on these critical files within the anthropics/claude-plugins-community repository:

• .claude-plugin/marketplace.json – The central registry containing all plugin entries with their respective source blocks defining Git URLs and commit SHAs.

• <plugin-dir>/.claude-plugin/plugin.json – Individual plugin descriptors containing metadata and configuration schemas. The TRES Finance implementation at tres-finance-plugin/.claude-plugin/plugin.json demonstrates the userConfig structure for API key requirements.

• README.md (within each plugin directory) – Human-readable documentation providing usage instructions and setup details specific to that plugin.

Summary

• Centralized registry: Claude Plugins Community maintains a single marketplace manifest at .claude-plugin/marketplace.json that indexes all available plugins.
• Two sourcing methods: The manifest supports url type for root-level repositories and git-subdir type for plugins nested within subdirectories.
• Version pinning: Every plugin entry specifies exact commit SHAs or refs to ensure reproducible installations across different environments.
• Descriptor validation: After fetching code, Claude Code loads .claude-plugin/plugin.json to verify metadata and prompt for required user configuration.
• Extensible architecture: Community members add new plugins by appending entries to the manifest with appropriate source fields, enabling decentralized development with centralized discovery.

Frequently Asked Questions

What is the primary registry file for Claude Plugins Community?

The primary registry is .claude-plugin/marketplace.json located at the repository root. This file contains a JSON array of all published plugins, with each object specifying the plugin's metadata and a source block that defines how Claude Code should fetch the code.

What Git source types does the marketplace manifest support?

The manifest supports two source types: url for repositories where the plugin resides at the root (requiring url and sha fields), and git-subdir for plugins located within subdirectories of larger repositories (requiring url, path, ref, and optionally sha fields).

How does Claude Plugins Community ensure reproducible plugin installations?

Every plugin entry in the marketplace manifest pins the code to a specific commit using the sha field (or ref for branches/tags in git-subdir sources). This guarantees that all users install the exact same code version regardless of when the installation occurs or how the upstream repository evolves.

Where is plugin-specific metadata stored after sourcing?

After cloning the repository, Claude Code looks for .claude-plugin/plugin.json within the fetched plugin directory. This descriptor file, as seen in the TRES Finance example at tres-finance-plugin/.claude-plugin/plugin.json, contains the plugin's name, version, author information, and any userConfig fields requiring user input such as API keys.

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