Source Types for Plugins in marketplace.json: url vs git-subdir Explained

The marketplace.json manifest in anthropics/claude-plugins-community defines two distinct source types for plugins—url for full repository clones and git-subdir for subdirectory extraction—each requiring specific fields to pinpoint the exact commit and location of plugin source code.

The anthropics/claude-plugins-community repository maintains a centralized plugin registry that tells Claude Desktop how to discover and install community plugins. Located at .claude-plugin/marketplace.json, this master manifest contains a source object for every plugin entry that dictates retrieval methods. Understanding the different source types for plugins in marketplace.json is essential for both plugin contributors and developers debugging installation issues.

Overview of marketplace.json Source Types

Every plugin entry in .claude-plugin/marketplace.json includes a source object with a mandatory source field. This field accepts exactly two values: url or git-subdir. These values determine whether Claude Desktop clones an entire repository or extracts a specific subdirectory, covering all current entries in the manifest with no other source types used.

The url Source Type (Full Repository)

Use the url source type when a plugin occupies its own dedicated repository. This method clones the entire Git repository at a specific commit hash.

Required fields:

• url: The full HTTPS URL of the remote Git repository
• sha: The exact commit hash to checkout for reproducible builds

{
  "name": "0x",
  "description": "Query 0x data...",
  "source": {
    "source": "url",
    "url": "https://github.com/0xProject/0x-ai.git",
    "sha": "0167bbb411cc972b966127d23c23de801061fa99"
  },
  "homepage": "https://github.com/0xProject/0x-ai"
}

According to the source code, the url type appears in entries like the 0x plugin, where the sha field locks the installation to a specific commit in 0xProject/0x-ai.

The git-subdir Source Type (Subdirectory Extraction)

Use the git-subdir source type for plugins housed within larger mono-repos or when only a specific folder contains the plugin logic. This method fetches only the designated subdirectory rather than the entire repository history.

Required fields:

• url: The repository URL (can be HTTPS or the owner/repo shorthand)
• path: The relative path to the plugin directory within the repository
• ref: The branch name or tag to reference (e.g., v1.0.1)
• sha: The specific commit hash that corresponds to the ref

{
  "name": "42minds",
  "description": "API security testing...",
  "source": {
    "source": "git-subdir",
    "url": "42Crunch-AI/claude-plugins",
    "path": "plugins/api-security-testing",
    "ref": "v1.0.1",
    "sha": "30287f5e3f122a646d1ac5ca3ab96e130c52a3ad"
  },
  "homepage": "https://docs.42crunch.com"
}

As implemented in anthropics/claude-plugins-community, the git-subdir type enables organizations to maintain multiple plugins in a single repository while allowing Claude Desktop to extract only the relevant code.

Comparing url vs git-subdir

Choose your source type based on your repository structure:

• url: Select this for single-plugin repositories where the project root contains the .claude-plugin/plugin.json file. This is the simpler option for standalone projects.
• git-subdir: Select this for mono-repos containing multiple plugins, shared libraries, or when the plugin code lives in a nested directory structure. This minimizes download size and keeps related plugins organized.

Both methods require a sha field to ensure reproducible installations, preventing breaking changes from future commits affecting existing Claude Desktop users.

Summary

• Two source types exist: url (full clone) and git-subdir (partial extraction) are the only values used in .claude-plugin/marketplace.json.
• Field requirements differ: url requires url and sha; git-subdir additionally requires path and ref.
• Commit pinning is mandatory: Both types use the sha field to lock plugins to specific commits for security and reproducibility.
• Mono-repo support: The git-subdir type enables efficient plugin distribution from large repositories without downloading unnecessary files.

Frequently Asked Questions

What file contains the plugin source type definitions?

The source types are defined in .claude-plugin/marketplace.json at the root of the anthropics/claude-plugins-community repository. This file serves as the master manifest that Claude Desktop queries to discover available community plugins.

What is the difference between the ref and sha fields in git-subdir?

The ref field specifies the human-readable branch name or tag (like v1.0.1) for reference purposes, while the sha field provides the immutable 40-character commit hash that Claude Desktop actually checks out. The sha ensures that installations remain deterministic even if the tag moves to a different commit later.

Can I use the url source type for a plugin located in a subdirectory?

No. The url source type clones the entire repository and expects the plugin metadata to exist at the root level. If your plugin lives in a subdirectory—such as within a mono-repo—you must use the git-subdir source type with the path field pointing to the correct directory.

Are there any other source types available besides url and git-subdir?

According to the source code analysis of anthropics/claude-plugins-community, only url and git-subdir appear in the marketplace manifest. These two types cover all current plugin entries, and no alternative source values are implemented in the file.

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