What Are the Two Source Shapes for Plugin Entries in marketplace.json?

The anthropics/claude-plugins-community repository defines exactly two source shapes for plugin entries in marketplace.json: url for standalone Git repositories and git-subdir for plugins located within monorepo subdirectories.

The Claude plugin marketplace uses a centralized manifest file to register community contributions. Understanding these two source shapes for plugin entries in marketplace.json ensures your plugin is discoverable and correctly retrieved by the marketplace parser, whether you maintain a standalone repository or manage multiple plugins within a shared codebase.

The URL Source Shape

The url source shape is designed for standalone plugins that reside in their own dedicated Git repositories. According to the source code in .claude-plugin/marketplace.json (lines 16‑19), this shape instructs the marketplace to clone the entire repository to access the plugin code.

When using the url shape, the source object must contain three specific fields:

• source: The string literal "url"
• url: A valid HTTPS Git URL pointing to the repository
• sha: The exact commit hash to checkout for reproducible builds

For example, the 0x AI plugin entry demonstrates this structure:

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

The Git-Subdir Source Shape

The git‑subdir source shape accommodates plugins that live within subdirectories of larger monorepos. As shown in .claude-plugin/marketplace.json (lines 56‑61), this shape allows multiple plugins to share a single repository while maintaining independent versioning through specific path references.

This shape requires five mandatory fields:

• source: The string literal "git-subdir"
• url: The repository URL
• path: The subdirectory path within the repo containing the plugin
• ref: The branch or tag name to reference
• sha: The exact commit hash for the pinned version

The 42Crunch API Security Testing plugin exemplifies this configuration:

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

Summary

• The url shape clones entire repositories for standalone plugins, requiring only the repo URL and commit SHA according to lines 16‑19 of .claude-plugin/marketplace.json.
• The git-subdir shape targets specific paths within monorepos, requiring additional path and ref fields alongside the URL and SHA as implemented in lines 56‑61.
• Both shapes enforce immutable builds by requiring the sha field, ensuring the marketplace retrieves the exact code version specified.

Frequently Asked Questions

Can I use SSH URLs instead of HTTPS for the source shapes?

The manifest specification in anthropics/claude-plugins-community explicitly requires HTTPS Git URLs for the url shape to ensure secure, non-interactive cloning by automated systems. While git-subdir entries may use shorthand repository identifiers, the underlying retrieval mechanism expects HTTPS protocols for authentication-free access.

Why does the git-subdir shape require both a ref and a sha?

The ref field provides a human-readable branch or tag name for maintenance and documentation purposes, while the sha supplies the immutable commit hash that the marketplace parser actually checks out. This dual-reference system allows developers to specify intent via the ref while guaranteeing reproducible builds through the cryptographic sha verification.

Are there additional source shapes planned for future marketplace.json versions?

According to the current source code analysis, the marketplace manifest only recognizes these two distinct shapes. Every plugin entry in .claude-plugin/marketplace.json must conform to either the standalone repository model (url) or the monorepo subdirectory model (git-subdir), with no alternative source types currently supported.

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