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

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 that uses this distribution method includes a structured source block:

{
  "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:

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

The script .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

The .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 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 Configuration

A plugin hosted within a sub-directory must include the source configuration in its local manifest at quickdesign/.claude-plugin/plugin.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 aggregates all available plugins, including those distributed via sub-directories:

{
  "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. This verification occurs in the .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 (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.

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