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

> Learn how to specify a plugin from a Git subdirectory in Claude Plugins. This guide simplifies the process for developers using the anthropics/claude-plugins-community repository.

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

---

---

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

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) with the correct source configuration:

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

```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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) files exist within those subdirectories before allowing merge.

## Summary

- **Use `source: "git-subdir"`** in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) checks for these required files during pull request review.