[FEATURE] Support `path` field in `github` and `url` plugin source types

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The current plugin source schema for github and url types in marketplace.json only supports repo/url, ref, and sha:

{
  "source": {
    "source": "github",
    "repo": "awslabs/agent-plugins",
    "ref": "main"
  }
}

When Claude Code clones a plugin from this source, it looks for .claude-plugin/plugin.json at the repository root. If the plugin lives in a subdirectory (e.g., plugins/deploy-on-aws/), it is never found. The debug log confirms: "Plugin deploy-on-aws has no entry.skills defined".

This is already causing real issues in the official marketplace:

• claude-plugins-official#450 — Semgrep plugin commands not recognized because the actual plugin content is nested under plugin/, not at the repo root
• claude-plugins-official PR #499 (closed) — Attempted to add awslabs/agent-plugins monorepo plugins individually, but each entry pointed to the same repo URL with no way to specify subdirectories

The marketplace-level source types (github, git) in strictKnownMarketplaces / extraKnownMarketplaces settings already support path and sparsePaths:

{
  "source": "github",
  "repo": "owner/repo",
  "ref": "main",
  "path": ".claude-plugin/marketplace.json",
  "sparsePaths": ["plugins/"]
}

But the plugin-level source types within marketplace.json do not. This inconsistency means plugin authors and marketplace curators must resort to workarounds for any monorepo-hosted plugin.

Proposed Solution

Add an optional path field to the github and url plugin source objects in marketplace.json:

GitHub source:

{
  "name": "deploy-on-aws",
  "description": "Deploy applications to AWS with architecture recommendations and IaC deployment.",
  "source": {
    "source": "github",
    "repo": "awslabs/agent-plugins",
    "path": "plugins/deploy-on-aws"
  }
}

Git URL source:

{
  "name": "my-plugin",
  "source": {
    "source": "url",
    "url": "https://github.com/org/monorepo.git",
    "path": "packages/claude-plugin"
  }
}

Expected behavior when path is specified on a plugin source:

1. Clone the repository (respecting ref / sha if present)
2. Resolve the plugin root to <clone_dir>/<path> instead of <clone_dir>
3. Look for .claude-plugin/plugin.json inside that resolved directory
4. Cache and load from the subdirectory

Schema change — add path: z.string().optional() to both object variants in the plugin source Zod union:

// "url" source type
z.object({
  source: z.literal("url"),
  url: z.string().endsWith(".git"),
  ref: z.string().optional(),
  sha: z.string().length(40).regex(/^[0-9a-f]+$/).optional(),
  path: z.string().optional()  // NEW
})

// "github" source type
z.object({
  source: z.literal("github"),
  repo: z.string(),
  ref: z.string().optional(),
  sha: z.string().length(40).regex(/^[0-9a-f]+$/).optional(),
  path: z.string().optional()  // NEW
})

Alternative Solutions

| Workaround | Limitation |
|---|---|
| Use the monorepo as a full marketplace (/plugin marketplace add) | Forces users to adopt the entire marketplace; doesn't work when curating plugins from multiple sources into a single marketplace |
| Create standalone repos per plugin | Repository sprawl; breaks development workflows; requires maintaining mirrors |
| Use git submodules in the marketplace repo | Adds complexity; fragile sync; poor DX |
| Verbose component fields (commands, skills, agents, etc.) with relative paths | Error-prone; the full repo is still cloned; doesn't solve .claude-plugin/plugin.json discovery |

Priority

Critical - Blocking my work

Feature Category

MCP server integration

Use Case Example

Example scenario:

1. An organization maintains a monorepo of Claude Code plugins at github.com/awslabs/agent-plugins with the layout plugins/deploy-on-aws/, plugins/cost-optimizer/, etc.
2. The official claude-plugins-official marketplace wants to list deploy-on-aws as an external plugin
3. The marketplace curator adds an entry to marketplace.json with "source": { "source": "github", "repo": "awslabs/agent-plugins", "path": "plugins/deploy-on-aws" }
4. When a user runs /plugin install deploy-on-aws@claude-plugin-directory, Claude Code clones the monorepo, resolves the subdirectory, and finds .claude-plugin/plugin.json at plugins/deploy-on-aws/.claude-plugin/plugin.json
5. This avoids requiring awslabs to split each plugin into its own repository or the user to adopt the entire awslabs marketplace

Additional Context

Existing tracking:

• anthropics/claude-code#15439 — [FEATURE] Support ref and path parameters in plugin source schema (open, labeled enhancement, area:packaging, area:mcp)
• anthropics/claude-code#20268 — [FEATURE] Support subdirectory path for GitHub plugin source (closed as duplicate of #15439)

Related issues showing community demand:

• claude-plugins-official#450 — Semgrep plugin broken by this limitation
• claude-plugins-official PR #499 — Community contribution closed because the feature doesn't exist
• claude-code#28426 — Sparse checkout request that also depends on knowing the plugin path
• claude-code#29485 — Confusion about relative path resolution in marketplace.json

Implementation note: A recommended patch (fix15439.patch) accompanies this issue, covering changes to the plugin source schema, cache resolver, install function, and marketplace plugin loader.

fix15439.patch