`url` vs `git-subdir` Source Types in `marketplace.json`: What's the Difference?

The url source type clones an entire repository at a specific commit, while git-subdir isolates a single folder from a larger repository—letting you publish plugins from monorepos without exposing unrelated code.

The marketplace.json file in the anthropics/claude-plugins-community repository controls how the Claude Marketplace fetches plugin source code. When adding your plugin, you must choose between two source types that differ fundamentally in scope: one captures a whole repository, the other extracts a specific sub-directory. Both resolve to an exact commit SHA for reproducible builds.

---

How the url Source Type Works

The url source type is the simpler option. It clones the entire Git repository and treats the repository root as the plugin's base directory.

Required Fields for url

Field	Description
url	Full HTTPS Git URL to the repository
sha	Exact commit SHA to checkout

Real-World Example: 0x Plugin

In .claude-plugin/marketplace.json (lines 17–20), the 0x plugin uses url because its code lives at the repository root:

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

Use url when your plugin occupies the entire repository—this is the most common case for standalone plugins.

---

How the git-subdir Source Type Works

The git-subdir source type targets a specific folder inside a repository. This is essential for monorepos that contain multiple plugins, shared libraries, or unrelated code you don't want exposed as part of your plugin.

Required Fields for git-subdir

Field	Description
url	HTTPS Git URL or short <owner>/<repo> format
path	Relative path inside the repo to the plugin folder
ref	Branch, tag, or commit reference to checkout
sha	Resolved exact commit SHA for immutability

Real-World Example: 42Crunch API Security Testing

In .claude-plugin/marketplace.json (lines 57–62), this plugin extracts only the plugins/api-security-testing folder from a larger repository:

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

Notice the shortcut URL format: 42Crunch-AI/claude-plugins resolves to the full HTTPS URL automatically. The ref field provides readability (humans see v1.0.1), while sha guarantees the exact code that runs.

---

Side-by-Side Comparison

Aspect	url	git-subdir
Scope	Entire repository	Single sub-directory
Use case	Standalone plugin repos	Monorepos with multiple plugins
URL format	Full HTTPS only	Full HTTPS or <owner>/<repo> shortcut
Path specification	Implicit (repo root)	Explicit path field required
Version reference	sha only	ref (human-readable) + sha (resolved)
Example repos	0x, single-purpose plugins	42Crunch, multi-plugin repositories

---

Adding a New Plugin: Code Templates

Template for Standalone Repository (url)

{
  "name": "my-awesome-plugin",
  "description": "A plugin that lives at the repo root",
  "source": {
    "source": "url",
    "url": "https://github.com/example/my-awesome-plugin.git",
    "sha": "a1b2c3d4e5f67890123456789abcdef123456789"
  },
  "homepage": "https://github.com/example/my-awesome-plugin"
}

Template for Monorepo Sub-Directory (git-subdir)

{
  "name": "my-subdir-plugin",
  "description": "A plugin inside a larger monorepo",
  "source": {
    "source": "git-subdir",
    "url": "example/monorepo",
    "path": "plugins/my-subdir-plugin",
    "ref": "main",
    "sha": "1234567890abcdef1234567890abcdef12345678"
  },
  "homepage": "https://github.com/example/monorepo"
}

---

Key Implementation Details from Source

The .claude-plugin/marketplace.json file is the authoritative source for plugin discovery in the Claude Marketplace. Each entry's source field determines how the Marketplace fetches code:

• sha immutability: Both source types resolve to a concrete SHA. Even when git-subdir uses a ref like v1.0.1, the sha field locks the exact commit.
• Path isolation: With git-subdir, only files under the specified path are exposed as the plugin; sibling directories remain inaccessible.
• URL flexibility: The git-subdir shortcut format reduces repetition for GitHub-hosted repositories.

The companion plugin.json file (located within each plugin's directory) provides per-plugin metadata, but marketplace.json controls the fetch mechanism.

---

Summary

• url — Clone entire repo, root directory is plugin. Use for standalone repositories.
• git-subdir — Clone repo, isolate specific folder. Use for monorepos with multiple plugins.
• Both require a resolved sha for reproducible, immutable builds.
• git-subdir adds path and ref fields for sub-directory targeting and human-readable versioning.
• Real implementations live in .claude-plugin/marketplace.json in the anthropics/claude-plugins-community repository.

---

Frequently Asked Questions

Can I use git-subdir with a full HTTPS URL instead of the shortcut?

Yes. The url field in git-subdir accepts either full HTTPS URLs (https://github.com/owner/repo.git) or the abbreviated <owner>/<repo> format. Both resolve to the same repository.

Why does git-subdir require both ref and sha?

The ref field provides a human-readable pointer—like main or v2.1.0—that helps developers understand which version is intended. The sha field guarantees immutability by locking the exact commit hash, protecting against tag changes or branch updates.

What happens if I use url for a plugin that isn't at the repository root?

The Marketplace will treat the repository root as your plugin, potentially exposing unwanted files or failing validation if plugin.json isn't found at that level. Use git-subdir with the correct path instead.

Is there a performance difference between url and git-subdir?

Both clone the full repository internally. The git-subdir type simply restricts which files are exposed to the plugin system after checkout. Network and storage costs are identical; the difference is purely organizational convenience.

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