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

> Configure a Claude plugin with git-subdir source type by updating marketplace.json. Learn to specify repo URL, subdirectory, and git reference for secure partial fetching.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-08-29

---

**To configure a Claude plugin using the `git-subdir` source type, add a JSON entry to [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json):

```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`](https://github.com/anthropics/claude-plugins-community/blob/main/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:

```bash

# 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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json):

```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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml).

The detection script at [`.github/actions/validate-plugins/scripts/00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.