Claude Plugin Source Types: url vs git-subdir Explained

The url source type retrieves an entire Git repository for a Claude plugin, whereas git-subdir performs a shallow clone and extracts only a specific subfolder, making it optimal for monorepos containing multiple plugins.

Claude plugins in the anthropics/claude-plugins-community repository are configured within the Marketplace manifest at .claude-plugin/marketplace.json. Each plugin's source object instructs the Claude MCP (Model Context Protocol) how to fetch the plugin code, offering two distinct retrieval strategies depending on whether your plugin lives at the repository root or within a subdirectory.

The url Source Type

The url source type provides the MCP with a complete repository view. When specified, the system clones the entire repository (or downloads a tarball) and checks out the code at the exact commit SHA provided.

How url Retrieval Works

When using the url source type, the entire repository becomes available to the plugin runtime. This approach is ideal when the plugin occupies the repository root or when the plugin requires access to files distributed across multiple directories in the project.

Required Fields for url

The url source type requires minimal configuration:

• source: Must be set to "url"
• url: The HTTPS URL of the Git repository
• sha (optional): The exact commit hash for reproducible builds

url Example: The 0x Plugin

As defined in .claude-plugin/marketplace.json (lines 16-19), the 0x plugin demonstrates the url pattern by pulling the complete repository:

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

The git-subdir Source Type

The git-subdir source type isolates a plugin to a specific directory within a larger repository. This method performs a shallow clone at the supplied ref (branch or tag), then extracts only the directory specified by the path field, ignoring the rest of the repository.

How git-subdir Retrieval Works

This source type reduces download size and prevents naming collisions when multiple plugins share a single monorepo. The MCP fetches only the necessary subdirectory, making it efficient for repositories like barnburner121/claude-plugin-marketplace that contain numerous plugins under a common parent directory.

Required Fields for git-subdir

The git-subdir source type accepts the following fields:

• source: Must be set to "git-subdir"
• url: The repository URL or shorthand (e.g., owner/repo)
• path: The subdirectory path containing the plugin code
• ref (optional): A human-readable branch or tag name
• sha (optional): The exact commit hash for immutable builds

git-subdir Example: 42Crunch API Security

The 42Crunch plugin (lines 56-61 of the manifest) retrieves only the plugins/api-security-testing folder:

{
  "name": "42crunch-api-security-testing",
  "source": {
    "source": "git-subdir",
    "url": "42Crunch-AI/claude-plugins",
    "path": "plugins/api-security-testing",
    "ref": "v1.0.1",
    "sha": "30287f5e3f122a646d1ac5ca3ab96e130c52a3ad"
  }
}

git-subdir Example: Multi-Plugin Monorepos

Many community plugins reside in the barnburner121/claude-plugin-marketplace repository under the generated-plugins/ directory. Each plugin defines its own subfolder path:

{
  "name": "a11y-fixer",
  "source": {
    "source": "git-subdir",
    "url": "barnburner121/claude-plugin-marketplace",
    "path": "generated-plugins/a11y-fixer",
    "ref": "main",
    "sha": "5f6b5d32d9f457dc9c2c7c0fb1d67dffc9140f33"
  }
}

Validation and Implementation

The repository's validation system distinguishes between these source types when detecting changes. According to the source code in .github/actions/validate-plugins/scripts/00-detect-changes.sh, the validation logic handles url and git-subdir entries differently when determining which plugins require re-validation during CI/CD workflows.

Key Differences Summary

Understanding when to use each source type ensures optimal repository organization:

• Scope of retrieval: url fetches the entire repository; git-subdir extracts only the specified path
• Use case: url suits single-repository plugins; git-subdir excels in monorepos containing multiple plugins
• Parameters: git-subdir accepts both ref (branch/tag) and sha, while url typically uses sha only
• Performance: git-subdir reduces download overhead by fetching only necessary files

When to Use Each Source Type

Choose url when your plugin constitutes an entire repository or requires access to files across multiple project directories. This approach simplifies configuration for standalone plugins.

Choose git-subdir when maintaining multiple plugins within a single monorepo or when your plugin lives as a subfolder within a larger project. This method prevents unnecessary data transfer and avoids path conflicts.

Summary

• The url source type in .claude-plugin/marketplace.json clones complete repositories, ideal for standalone plugins like the 0x example
• The git-subdir source type performs shallow clones of specific directories, perfect for monorepos like those used by 42Crunch and barnburner121
• Both types support immutable sha values for reproducible builds
• The git-subdir type uniquely accepts a ref parameter for human-readable version references
• Validation scripts in .github/actions/validate-plugins/scripts/00-detect-changes.sh process these source types differently during CI workflows

Frequently Asked Questions

Can I use git-subdir without specifying a ref?

Yes, the ref field is optional for git-subdir sources. However, you must provide either a ref or a sha to ensure the MCP can locate the correct commit. If both are provided, the system uses the ref to locate the branch or tag, then verifies the specific sha for immutability.

What happens if both ref and sha are provided in a git-subdir source?

When both parameters are present, the MCP resolves the ref (branch or tag name) to locate the general area of the repository history, then validates the exact sha to ensure the code matches the expected immutable state. This provides both human-readable versioning and cryptographic verification.

Is url or git-subdir better for a single plugin repository?

For single plugin repositories where the code lives at the root, use the url source type. This approach eliminates the need to specify a path parameter and provides the plugin runtime access to the entire repository context. The git-subdir type adds unnecessary complexity when the repository contains only one plugin.

How does the validation script handle different source types?

The validation script at .github/actions/validate-plugins/scripts/00-detect-changes.sh distinguishes between url and git-subdir entries when detecting which plugins have changed in a commit. This differentiation ensures that modifications to specific subdirectories in monorepos trigger validation only for the affected plugins, while standalone repository changes trigger validation for the complete url-based plugin.

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