What Is the "git‑subdir" Source Type for Claude Plugins? A Complete Guide

The git‑subdir source type lets the Claude plugins system install a plugin from a specific sub‑directory of a Git repository rather than the repository root, enabling multiple plugins to share one repo while maintaining independent versioning.

The git‑subdir source type is a core mechanism in the anthropics/claude-plugins-community ecosystem. It solves a practical problem: many organizations want to maintain several related plugins together without creating separate repositories for each one. This article explains exactly how git‑subdir works, what fields it requires, and how the validation pipeline processes these entries.

---

How the git‑subdir Source Type Works

When a plugin entry in .claude-plugin/marketplace.json declares "source": "git‑subdir", the system knows to look inside a repository subfolder rather than treating the entire repo as a single plugin.

The CLI performs three critical steps during validation or installation:

1. Clone the repository at the specified ref (branch, tag, or commit).
2. Verify that the checked‑out commit matches the supplied sha for integrity.
3. Navigate to the path subdirectory and load the plugin from that location.

This approach provides deterministic, reproducible builds — the sha ensures you get exactly the code you expect, even if the ref tag gets moved or deleted.

---

Required Fields for git‑subdir Entries

Every git‑subdir source must include four fields. These are validated by the scripts in .github/actions/validate-plugins/scripts/.

Field	Description	Example
url	GitHub repository identifier (owner/repo)	42Crunch-AI/claude-plugins
path	Relative path to the plugin's .claude-plugin folder	plugins/api-security-testing
ref	Branch, tag, or commit reference to checkout	v1.0.1 or main
sha	Full 40‑character commit SHA for verification	30287f5e3f122a646d1ac5ca3ab96e130c52a3ad

Missing any of these fields causes validation to fail. The sha must match exactly — the pipeline runs git rev-parse HEAD and compares against this value.

---

Real‑World Examples from the Repository

Two plugins in the official marketplace demonstrate typical git‑subdir usage patterns.

42Crunch API‑Security‑Testing Plugin

This entry at lines 57‑61 of .claude-plugin/marketplace.json pins a specific release:

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

Notice the use of a semantic version tag (v1.0.1) combined with an explicit SHA. This protects against tag rewriting attacks.

A11y‑Fixer Plugin

This entry at lines 79‑84 tracks a development branch:

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

The main branch reference here requires more frequent SHA updates as the plugin evolves.

---

Validation Pipeline Implementation

The git‑subdir source type is processed by two key scripts in the repository's GitHub Actions workflow.

Change Detection (00-detect-changes.sh)

The detection script identifies entries where the source is an object containing url and path fields rather than a simple string. This triggers the specialized git‑subdir validation path.

External Validation (30-validate-cli-external.sh)

This script implements the actual git‑subdir logic:

# Clone at specific ref

git clone --depth 1 --branch ${REF} https://github.com/${URL}.git ${TEMP_DIR}

# Verify SHA integrity

ACTUAL_SHA=$(git -C ${TEMP_DIR} rev-parse HEAD)
if [ "${ACTUAL_SHA}" != "${EXPECTED_SHA}" ]; then
    echo "SHA mismatch: expected ${EXPECTED_SHA}, got ${ACTUAL_SHA}"
    exit 1
fi

# Load plugin from subdirectory

PLUGIN_ROOT="${TEMP_DIR}/${PATH}"
validate_plugin_json "${PLUGIN_ROOT}/.claude-plugin/plugin.json"

The shallow clone (--depth 1) keeps CI fast while still allowing full SHA verification.

---

Custom Plugin Manifest Template

To publish your own git‑subdir plugin, structure your marketplace.json entry like this:

{
  "name": "my-cool-plugin",
  "description": "Demo plugin stored in a sub-folder.",
  "source": {
    "source": "git-subdir",
    "url": "myorg/my-plugins-repo",
    "path": "plugins/my-cool-plugin",
    "ref": "v2.3.0",
    "sha": "a1b2c3d4e5f67890123456789abcdef012345678"
  },
  "homepage": "https://github.com/myorg/my-plugins-repo"
}

Place your actual plugin files — plugin.json, skills, icons — inside the plugins/my-cool-plugin/.claude-plugin/ directory of your repository.

---

Benefits of the git‑subdir Design

Using git‑subdir instead of repo‑per‑plugin provides several advantages:

• Code reuse — Shared utilities, test frameworks, or CI configurations live at the repository root.
• Atomic updates — Version‑bump multiple related plugins in a single commit.
• Reduced overhead — One repository to manage issues, permissions, and secrets instead of many.
• Deterministic installs — The ref + sha combination guarantees identical plugin code across all installations.

---

Summary

• git‑subdir enables plugins to reside in subdirectories of Git repositories, defined in .claude-plugin/marketplace.json.
• Four required fields control the behavior: url, path, ref, and sha.
• The validation pipeline at .github/actions/validate-plugins/scripts/30-validate-cli-external.sh clones, verifies, and extracts these plugins.
• Real examples include 42Crunch API‑Security‑Testing (lines 57‑61) and A11y‑Fixer (lines 79‑84) in the marketplace manifest.

---

Frequently Asked Questions

What happens if the sha field doesn't match the actual commit?

The validation script 30-validate-cli-external.sh performs an explicit check: it runs git rev-parse HEAD and compares the output to the expected SHA. If they differ, validation fails with an error message and the plugin is not accepted into the marketplace. This prevents supply‑chain attacks where a tag is moved to a different commit.

Can I use git‑subdir with private repositories?

The current marketplace validation is designed for public GitHub repositories. The scripts clone via https://github.com/${URL}.git without authentication. For private repositories, you would need to modify the validation pipeline to inject credentials or use deploy keys, which is not supported in the standard anthropics/claude-plugins-community workflow.

How do I update a git‑subdir plugin to a new version?

Update both the ref field (to the new tag or branch) and the sha field (to the full 40‑character commit hash) in your marketplace.json entry. The detection script 00-detect-changes.sh will flag this as a modification, triggering re‑validation. The PR must pass the SHA verification before merging.

Why use git‑subdir instead of a separate repository for each plugin?

git‑subdir reduces maintenance burden when you maintain multiple related plugins. You can share CI configurations, testing utilities, and documentation in the repository root while keeping each plugin independently versioned. This is especially valuable for organizations with plugin suites that share common code — the 42Crunch example demonstrates this pattern with multiple security tools in one repo.

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