How to Configure a Claude Plugin Using the git-subdir Source Type

To configure a Claude plugin using the git-subdir source type, add a JSON entry to .claude-plugin/marketplace.json with "source": "git-subdir", specifying the repository URL, sub-directory path, git reference, and commit SHA for secure, partial repository fetching.

The anthropics/claude-plugins-community repository supports multiple source types for plugin distribution, with git-subdir enabling efficient extraction of single directories from larger monorepos. This method allows plugin authors to maintain multiple plugins in one repository while allowing Claude to fetch only the specific code required for a given plugin.

Understanding the git-subdir Architecture

The git-subdir source type operates through three primary components according to the source code in anthropics/claude-plugins-community.

Marketplace Manifest (.claude-plugin/marketplace.json): This central catalog stores metadata for every published plugin. Each entry contains a "source" object where "source": "git-subdir" triggers sparse checkout behavior. The manifest at lines 57-61 contains the canonical example of this configuration structure.

Plugin Loader: When a user requests a plugin, the loader parses the manifest entry and executes a sparse checkout—or git archive operation—limited to the specified path. The loader verifies that the fetched content matches the exact sha declared in the manifest for integrity protection.

MCP Infrastructure: After extraction, the Claude-Plugin-Server (MCP) adds the directory to its plugin search path, registers skill definitions from SKILL.md files, and makes the plugin available to Claude.

Required Configuration Fields

A valid git-subdir configuration requires four specific fields within the source object. Here is the structure from lines 57-61 of .claude-plugin/marketplace.json:

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

• url: The GitHub repository name (owner/repo format) containing the plugin code.
• path: The relative path within that repository to the plugin's root directory (typically containing SKILL.md and assets).
• ref: The branch, tag, or commit reference to checkout. Tags are recommended for reproducible builds.
• sha: The exact commit SHA that the ref resolves to, enabling cryptographic verification of the fetched code.

How the Plugin Loader Processes git-subdir

When processing a git-subdir entry, the loader performs a sparse checkout rather than cloning the entire repository. This process reduces bandwidth consumption and prevents cross-plugin contamination in monorepo structures.

The loader executes the following operations internally:

# Initialize a sparse checkout of the specific subdirectory

git clone --depth 1 --filter=blob:none --no-checkout \
    https://github.com/example-org/awesome-plugins.git repo
cd repo
git sparse-checkout init --cone
git sparse-checkout set plugins/my-awesome-plugin
git checkout v2.3.0

After checkout, the loader validates the commit hash using git rev-parse HEAD and compares it against the sha field in the manifest. If the hashes match, the MCP server registers the plugin; if they differ, the operation fails to prevent tampering or drift.

Adding a git-subdir Plugin to the Manifest

To add a new plugin using this source type, append an object to the "plugins" array in .claude-plugin/marketplace.json:

{
  "name": "my-awesome-plugin",
  "description": "Example plugin living in a monorepo sub-directory.",
  "source": {
    "source": "git-subdir",
    "url": "example-org/awesome-plugins",
    "path": "plugins/my-awesome-plugin",
    "ref": "v2.3.0",
    "sha": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3"
  },
  "homepage": "https://github.com/example-org/awesome-plugins/tree/v2.3.0/plugins/my-awesome-plugin"
}

Ensure the path points to a directory containing a valid SKILL.md file defining the plugin's capabilities and configuration schema.

Validation and Security

The repository enforces strict validation of git-subdir entries through the CI pipeline defined in .github/workflows/validate-plugins.yml.

The detection script at .github/actions/validate-plugins/scripts/00-detect-changes.sh (line 94) specifically searches for entries with "source": "git-subdir" to enforce bundling restrictions. This ensures that:

1. Only the declared sub-directory is included in the plugin package
2. Cross-directory dependencies are explicitly declared
3. The sha field matches the actual content of the ref at validation time

The validation pipeline runs on every pull request, preventing malformed entries from reaching the marketplace manifest.

Summary

• Primary configuration file: .claude-plugin/marketplace.json stores all git-subdir plugin definitions.
• Required fields: url, path, ref, and sha must all be specified for security and precision.
• Sparse checkout: The loader uses git sparse-checkout to fetch only the specified sub-directory, reducing bandwidth and isolating plugins.
• Integrity verification: The loader validates the exact commit SHA against the manifest before registering the plugin with the MCP server.
• CI enforcement: The 00-detect-changes.sh script at line 94 specifically handles git-subdir entries to ensure proper bundling.

Frequently Asked Questions

What is the difference between git-subdir and a regular git source type?

A regular git source type clones the entire repository, while git-subdir performs a sparse checkout limited to the specified path. This distinction is critical for monorepos containing multiple plugins, as it prevents downloading unnecessary code and ensures plugin isolation. The git-subdir type also requires a sha field for cryptographic verification, which is optional in standard git configurations.

Can I use a branch name instead of a tag for the ref field?

Technically yes, but tags are strongly recommended. The ref field accepts any valid git reference (branch, tag, or commit hash), but branches are mutable. If the branch advances after you publish the plugin, the sha validation will fail unless you update the manifest. Using immutable tags or commit hashes ensures reproducible plugin behavior across all Claude instances.

How does the validation script detect git-subdir changes?

The script at .github/actions/validate-plugins/scripts/00-detect-changes.sh scans the marketplace manifest for "source": "git-subdir" entries (specifically referenced at line 94). When detected, the validation logic applies special bundling rules to ensure that only the files within the declared path are included in the plugin package, preventing accidental leakage of other repository contents.

What happens if the sha doesn't match the ref during loading?

The plugin loader rejects the installation and throws an integrity error. When the loader checks out the ref and runs git rev-parse HEAD, it compares the result against the manifest's sha field. A mismatch indicates that the tag was moved or the repository was compromised, triggering a security failure that prevents the MCP server from registering the plugin.

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