How to Specify a Plugin from a Git Subdirectory in Claude Plugins

---

Set the source field to git-subdir in your marketplace entry and provide the relative path to the plugin folder within the repository.

The Claude Plugins Community repository enables developers to host multiple plugins within a single Git repository by supporting sub-directory specifications. When you need to specify a plugin from a git subdirectory, you configure specific fields in the central .claude-plugin/marketplace.json registry file. This approach allows maintainers to bundle related plugins together while keeping the Claude Marketplace index clean and navigable.

Understanding the Git Subdirectory Configuration

The marketplace uses a single JSON file located at .claude-plugin/marketplace.json to index all available plugins. According to the anthropics/claude-plugins-community source code, the source field determines how the Claude Marketplace fetches plugin code. When this value is set to git-subdir, the loader understands that the plugin manifest and source code reside within a specific subfolder of the repository rather than at the root level.

This configuration is essential for monorepo setups where multiple plugins share infrastructure, documentation, or common utilities. The loader treats the specified subdirectory as an isolated plugin root, expecting to find a .claude-plugin folder containing plugin.json and any required assets.

Required Fields for Git Subdirectory Plugins

To specify a plugin from a git subdirectory, your marketplace entry must include these fields:

• url: The HTTPS URL of the upstream Git repository.
• source: Must be set to git-subdir to trigger subdirectory-aware cloning logic.
• path (optional): The relative path inside the repository pointing to the plugin's root directory. If omitted, the repository root is used.
• commit, tag, or branch (optional): Pin the exact revision to load. If none is supplied, the repository's default branch is used.

The path field is relative to the repository root and should point to the folder containing the .claude-plugin directory. For version pinning, supplying a specific commit SHA ensures deterministic builds, while tag or branch allows for automatic updates within constraints.

Real-World Example from marketplace.json

The live marketplace file contains multiple entries demonstrating this pattern. Below is a concrete example showing how to reference code nested deep within a repository:

{
  "name": "adcontextprotocol-adcp-client",
  "url": "https://github.com/adcontextprotocol/adcp-client.git",
  "source": "git-subdir",
  "path": "plugins/adcp-client",
  "commit": "a1b2c3d4e5f6g7h8i9j0",
  "description": "Client library for the ADCP protocol.",
  "homepage": "https://github.com/adcontextprotocol/adcp-client"
}

In this entry, the source: "git-subdir" field instructs the marketplace loader to look inside the plugins/adcp-client folder rather than the repository root. The commit field pins the exact revision, ensuring reproducible installations regardless of subsequent changes to the default branch.

How the Loader Processes Git Subdirectories

When the Claude plugin loader encounters a git-subdir source entry, it executes the following sequence:

1. Clone the repository defined by the url field into a temporary workspace.
2. Checkout the specified commit, tag, or branch. If none is provided, it uses the repository's default branch.
3. Navigate to the directory specified by the path field. If path is omitted, it remains at the repository root.
4. Validate that the target directory contains a .claude-plugin folder with a valid plugin.json manifest.

Because the loader isolates the specified subdirectory, you can safely host dozens of plugins in a single repository without causing name collisions or forcing users to download unnecessary code.

Adding Your Own Git Subdirectory Plugin

Follow these steps to register a plugin located in a subfolder of your repository.

Step 1: Configure the Marketplace Entry

Add an object to .claude-plugin/marketplace.json with the correct source configuration:

{
  "name": "my-awesome-plugin",
  "url": "https://github.com/username/awesome-plugins.git",
  "source": "git-subdir",
  "path": "my-plugin",
  "branch": "main",
  "description": "An example plugin living in a sub-folder.",
  "homepage": "https://github.com/username/awesome-plugins"
}

Step 2: Create the Plugin Manifest

Inside your repository, create the file at my-plugin/.claude-plugin/plugin.json:

{
  "name": "my-awesome-plugin",
  "description": "An example plugin living in a sub-folder.",
  "version": "0.1.0",
  "entrypoint": "main.py",
  "api": "v1"
}

Step 3: Validate with CI

The repository includes a validation workflow at .github/workflows/validate-plugins.yml that automatically checks all marketplace entries. This workflow verifies that git-subdir entries point to valid paths and that the required plugin.json files exist within those subdirectories before allowing merge.

Summary

• Use source: "git-subdir" in .claude-plugin/marketplace.json to indicate that a plugin resides within a repository subfolder.
• Specify the path field to point to the directory containing the .claude-plugin folder.
• Pin versions using commit, tag, or branch fields to control exactly which code revision the marketplace loads.
• Host multiple plugins in a single repository by creating separate marketplace entries, each pointing to a different subdirectory via unique path values.

Frequently Asked Questions

What is the difference between git-subdir and standard git sources?

Standard git sources assume the plugin manifest exists at the repository root, while git-subdir explicitly tells the loader to navigate into a specific folder before looking for the .claude-plugin directory. Without source: "git-subdir", the marketplace would fail to locate plugins nested inside monorepos or subdirectories.

Can I omit the path field when using git-subdir?

Yes, the path field is optional. If omitted, the loader treats the repository root as the plugin directory. However, omitting path defeats the primary purpose of using git-subdir, which is to isolate plugins located in subfolders. Always include path when the plugin code lives anywhere other than the repository root.

How do I pin a specific version of a subdirectory plugin?

Add a commit field containing the full SHA hash, or use tag or branch for named references. The loader checks out this specific revision after cloning the repository but before navigating to the path subdirectory. This ensures that even if the default branch changes, the marketplace loads the exact version you specified.

What files must exist inside the git subdirectory?

The subdirectory must contain a .claude-plugin folder, which must include at minimum a plugin.json manifest file. Optionally, you may include icon.svg or other assets referenced by your manifest. The validation workflow in .github/workflows/validate-plugins.yml checks for these required files during pull request review.

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