What Are the Claude Plugin Source Types? A Complete Guide to the Marketplace Schema

Claude plugins support two source types—url for direct Git repository links and git-subdir for sub-directories within remote repositories—defined in the .claude-plugin/marketplace.json file.

The anthropics/claude-plugins-community repository defines how community plugins are distributed through a standardized configuration schema. Understanding the Claude plugin source types is essential for developers who want to publish or consume extensions in the Claude ecosystem, as these definitions determine how Claude fetches and validates plugin code.

Understanding the Claude Plugin Marketplace Structure

The canonical definitions for all supported source formats reside in .claude-plugin/marketplace.json. This file contains an array of plugin objects, each specifying a source object that tells Claude exactly where to retrieve the plugin's code and which version to use.

Claude Plugin Source Types Explained

The marketplace currently recognizes two distinct Claude plugin source types, each designed for different repository layouts.

URL-Based Sources (url)

The url source type points to a direct Git repository URL. When Claude processes this entry, it clones the entire repository. If a sha is provided, the checkout is pinned to that specific commit hash for reproducibility.

This approach works best for repositories that contain a single plugin at the root level.

Git Subdirectory Sources (git-subdir)

The git-subdir source type targets a specific sub-directory within a remote Git repository. This is ideal for monorepos hosting multiple plugins. In addition to the repository url, this type requires:

• path: The sub-directory containing the plugin
• ref: The branch or tag to checkout
• sha: The specific commit hash for pinning

Implementation Examples from the Source Code

Here are concrete examples extracted from the community marketplace showing how each source type is configured.

URL-based source example (from the "0x" plugin):

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

Git-subdir source example (from the "42crunch-api-security-testing" plugin):

{
  "name": "42crunch-api-security-testing",
  "description": "Automate API security directly in Claude Code...",
  "source": {
    "source": "git-subdir",
    "url": "42Crunch-AI/claude-plugins",
    "path": "plugins/api-security-testing",
    "ref": "v1.0.1",
    "sha": "30287f5e3f122a646d1ac5ca3ab96e130c52a3ad"
  },
  "homepage": "https://docs.42crunch.com"
}

Key Configuration Files

Two files in the .claude-plugin directory govern how Claude plugin source types are processed:

• .claude-plugin/marketplace.json: The authoritative registry containing the full list of plugins and their source definitions. Each entry in this array uses one of the two supported source types.
• .claude-plugin/plugin.json: Top-level metadata for the community marketplace itself, which includes a default "source": {"source":"url","url":"./"} entry referencing the local repository.

Summary

• The anthropics/claude-plugins-community repository supports exactly two Claude plugin source types: url and git-subdir.
• Use url for standalone repositories where the plugin resides at the root.
• Use git-subdir for monorepos, specifying the path, ref, and sha for precise targeting.
• All source definitions live in .claude-plugin/marketplace.json, which serves as the canonical schema reference.
• Neither npm packages, direct file URLs, nor HTTP archives are supported as alternative source formats.

Frequently Asked Questions

What is the difference between url and git-subdir source types?

The url type clones an entire Git repository, expecting the plugin to exist at the root level. The git-subdir type checks out only a specific directory within a remote repository, making it suitable for organizations managing multiple plugins in a single monorepo.

How do I pin a specific version of a Claude plugin?

Both source types support version pinning via the sha field, which accepts a full Git commit hash. According to the schema in .claude-plugin/marketplace.json, providing a sha ensures Claude checks out that exact commit, guaranteeing reproducible builds regardless of subsequent repository changes.

Can I use npm packages or direct file URLs as sources?

No. As implemented in the anthropics/claude-plugins-community repository, the marketplace schema only recognizes Git-based sources. The .claude-plugin/marketplace.json file contains no support for npm packages, HTTP archives, or direct file system URLs outside of Git repositories.

Where is the official schema for Claude plugin source definitions?

The authoritative reference is .claude-plugin/marketplace.json in the root of the anthropics/claude-plugins-community repository. This file contains the complete registry of validated plugins and demonstrates the exact JSON structure required for each source type, including mandatory and optional fields like sha, ref, and path.

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