# How the `source.git-subdir` Option Works for Claude Plugin Distribution

> Learn how the source git-subdir option in anthropics/claude-plugins-community allows multiple Claude plugins in one repo by isolating plugin roots to specific subdirectories. Distribute plugins efficiently.

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

---

**The `source.git-subdir` option enables multiple Claude plugins to reside in a single Git repository by specifying a sub-directory path that the plugin loader treats as an isolated plugin root.**

In the `anthropics/claude-plugins-community` repository, plugin distribution supports two primary source types: direct `url` links to archives and the `git-subdir` method for monorepo-style hosting. The `source.git-subdir` configuration allows developers to maintain several independent plugins—such as `quickdesign`, `testdino`, and `eli5`—within one repository while ensuring each sub-directory operates as a standalone plugin with independent integrity checks and dependency resolution.

## Understanding the `source.git-subdir` Configuration

The `source.git-subdir` option requires three specific fields in the plugin manifest: `source` (set to `"git-subdir"`), `repo` (the Git repository URL), and `subdir` (the path to the plugin folder).

Unlike the `url` source type, which downloads a complete archive, `git-subdir` instructs Claude’s plugin loader to perform a targeted extraction. This approach preserves **SHA-256 integrity verification** and **runtime isolation** while reducing repository fragmentation across the ecosystem.

### The Marketplace Manifest Structure

Each plugin entry in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) that uses this distribution method includes a structured source block:

```json
{
  "name": "quickdesign",
  "source": {
    "source": "git-subdir",
    "repo": "https://github.com/anthropics/claude-plugins-community",
    "subdir": "quickdesign"
  },
  "sha256": "c2a7e8f…",
  "metadata": {}
}

```

The `sha256` hash applies specifically to the contents of the `subdir` folder, not the entire repository, ensuring reproducible builds regardless of other changes in the monorepo.

## Technical Implementation in the Plugin Loader

When processing a `git-subdir` entry, the loader executes a three-stage workflow: repository cloning, sub-directory isolation, and integrity verification.

### Repository Cloning and Subdirectory Isolation

The loader performs a shallow clone of the specified `repo` URL, then constructs the plugin path by joining the clone directory with the `subdir` value:

```python
def load_plugin(entry):
    if entry["source"]["source"] == "git-subdir":
        repo_url = entry["source"]["repo"]
        subdir = entry["source"]["subdir"]
        clone_dir = git.clone(repo_url)           # shallow clone for speed

        plugin_dir = os.path.join(clone_dir, subdir)
        verify_sha256(plugin_dir, entry["sha256"])
        run_plugin(plugin_dir)                    # reads plugin.json inside subdir

```

This isolation ensures that build commands, asset resolution, and runtime environments execute exclusively within the sub-directory boundaries, preventing cross-contamination between plugins hosted in the same repository.

### Integrity Verification with SHA-256

The validation system computes the content hash of the isolated sub-directory and compares it against the `sha256` value stored in the marketplace manifest. This verification occurs during both the CI validation phase and runtime loading, guaranteeing that the plugin contents match the cryptographically signed version approved for distribution.

## Validation and CI Pipeline

The `anthropics/claude-plugins-community` repository employs specialized GitHub Actions workflows to validate `git-subdir` entries without processing the entire repository contents unnecessarily.

### Change Detection in [`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh)

The script [`.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) identifies which plugins require re-validation by detecting modifications to their specific sub-directories. It distinguishes between `git-subdir` and `url` source types to apply appropriate detection logic, ensuring that changes to one plugin in a monorepo do not trigger validation cascades for unchanged siblings.

### External Validation in [`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh)

The [`.github/actions/validate-plugins/scripts/30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/30-validate-cli-external.sh) script handles the actual verification workflow for external repositories. For `git-subdir` entries, this script:

1. Clones the specified repository URL
2. Navigates to the `subdir` path specified in the manifest
3. Verifies the presence of [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) within that sub-directory
4. Validates required assets and dependency declarations

This validation ensures that every `git-subdir` plugin meets the same quality and security standards as standalone repository distributions.

## Practical Examples

Implementing `source.git-subdir` requires configuration in both the plugin's local manifest and the central marketplace registry.

### Minimal [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) Configuration

A plugin hosted within a sub-directory must include the source configuration in its local manifest at [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json):

```json
{
  "name": "quickdesign",
  "version": "0.1.0",
  "description": "A quick-design assistant for Claude.",
  "source": {
    "source": "git-subdir",
    "repo": "https://github.com/anthropics/claude-plugins-community",
    "subdir": "quickdesign"
  },
  "entrypoint": "python -m quickdesign",
  "runtime": "python3.11"
}

```

This self-referential configuration allows the plugin to declare its own distribution method, enabling the validation scripts to verify consistency between the local manifest and the marketplace registry.

### Real-World Manifest Entry

The central [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) aggregates all available plugins, including those distributed via sub-directories:

```json
{
  "plugins": [
    {
      "name": "quickdesign",
      "source": {
        "source": "git-subdir",
        "repo": "https://github.com/anthropics/claude-plugins-community",
        "subdir": "quickdesign"
      },
      "sha256": "c2a7e8f…",
      "metadata": {}
    },
    {
      "name": "testdino",
      "source": {
        "source": "git-subdir",
        "repo": "https://github.com/anthropics/claude-plugins-community",
        "subdir": "testdino"
      },
      "sha256": "b4d9e1a…",
      "metadata": {}
    }
  ]
}

```

Both `quickdesign` and `testdino` reside in the same parent repository but maintain independent versioning and integrity hashes through their respective `subdir` specifications.

## Summary

- The `source.git-subdir` option enables **monorepo architecture** for Claude plugins, allowing multiple independent plugins to coexist within a single Git repository.
- The loader performs **shallow cloning** and **sub-directory isolation**, treating the specified folder as a standalone plugin root with full integrity verification.
- Configuration requires three fields in the marketplace manifest: `source: "git-subdir"`, `repo` (URL), and `subdir` (path).
- The CI validation pipeline in `.github/actions/validate-plugins/scripts/` specifically handles `git-subdir` entries by cloning repositories and verifying sub-directory contents against SHA-256 hashes.
- This distribution method maintains the same **security guarantees** and **runtime isolation** as standalone repository distributions while reducing administrative overhead for plugin collections.

## Frequently Asked Questions

### What is the difference between `url` and `git-subdir` source types in Claude plugins?

The `url` source type points to a complete tarball or zip archive containing the entire plugin, while `git-subdir` specifies a sub-directory within a larger Git repository. The `git-subdir` method clones the full repository but isolates only the specified folder as the plugin root, enabling multiple plugins to reside in a single monorepo without sacrificing integrity verification or runtime isolation.

### How does the validation system ensure `git-subdir` plugins haven't been tampered with?

The validation system computes a **SHA-256 hash** of the specific sub-directory contents and compares it against the hash stored in the marketplace manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). This verification occurs in the [`.github/actions/validate-plugins/scripts/30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/30-validate-cli-external.sh) script during CI and is checked again during runtime loading, ensuring cryptographic integrity regardless of changes elsewhere in the repository.

### Can a plugin using `source.git-subdir` reference files outside its sub-directory?

No, the plugin loader treats the specified `subdir` as an isolated root directory. Build commands, asset resolution, and runtime environments execute exclusively within that folder boundary. The loader constructs the plugin path using `os.path.join(clone_dir, subdir)`, effectively sandboxing the plugin and preventing access to parent directory resources for security and reproducibility.

### Where is the `source.git-subdir` configuration defined in the repository structure?

The configuration appears in two locations: the **central marketplace manifest** at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) (which lists all available plugins and their distribution methods) and the **plugin's local manifest** at `<subdir>/.claude-plugin/plugin.json` (which declares the plugin's own source configuration). The GitHub Actions validation scripts verify consistency between these two definitions during the CI pipeline.