[FEATURE] Support `ref` and `path` parameters in plugin source schema

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

Currently, the plugin source schema in marketplace.json does not support ref (git reference) or path (subdirectory) parameters for individual plugin sources. This creates significant friction for plugin development workflows and forces developers into suboptimal repository structures.

Current Limitations:

1. No Version Control for Individual Plugins

• Cannot pin plugins to specific git tags, branches, or commits
• Must version the entire marketplace.json instead of individual plugins
• Difficult to test different plugin versions without modifying marketplace configuration

1. No Subdirectory Support in Plugin Sources

• Entire repository is cloned for plugins, even if plugin lives in a subdirectory
• Forces either monorepo approach or moving plugin to repository root
• Creates namespace conflicts during local development

1. Development Environment Pollution

• When developing a plugin within its repo and launching Claude Code for development work, the plugin's .mcp.json is automatically loaded into the Claude Code session
• Development files (tests, build scripts, documentation) mix with plugin distribution files
• No clean separation between "what gets distributed" and "what's for development"
• Unclear whether Claude Code caches entire repo or just plugin contents

1. Cumbersome Current Workarounds

• Component configuration fields (commands, agents, skills, etc.) are verbose and repetitive
• Must manually specify every component type
• Easy to miss a component type when configuring
• Doesn't solve development environment pollution or version control issues

Proposed Solution

Add ref and path parameters to the plugin source schema, matching the existing syntax already used in strictKnownMarketplaces for marketplace sources.

Proposed Syntax:

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-plugins",
  "owner": {
    "name": "Developer"
  },
  "plugins": [
    {
      "name": "terraform-core",
      "source": {
        "source": "url",
        "url": "https://gitea.example.com/org/terraform-plugin.git",
        "ref": "v1.0.0",        // NEW: Branch, tag, or commit SHA
        "path": "plugin"         // NEW: Subdirectory within repository
      },
      "description": "Terraform standards plugin",
      "version": "1.0.0"
    },
    {
      "name": "terraform-aws",
      "source": {
        "source": "github",
        "repo": "org/terraform-aws-plugin",
        "ref": "develop",        // NEW: Test pre-release versions
        "path": "plugin"         // NEW: Plugin in subdirectory
      },
      "description": "AWS-specific Terraform plugin"
    }
  ]
}

Field Specifications:

• ref (optional)
• Type: string
• Valid values: git branch name, tag, or commit SHA
• Examples: "main", "v1.0.0", "abc123def456"
• Default: repository's default branch if not specified

• path (optional)
• Type: string
• Valid values: relative path to subdirectory within repository
• Examples: "plugin", "packages/claude-plugin", "tools/plugins/formatter"
• Default: repository root if not specified

Key Benefits:

1. Clean Development Environment - Plugin subdirectory keeps development files separate from distribution files, preventing .mcp.json conflicts
2. Version Control - Pin plugins to specific git tags, branches, or commits for stability and testing
3. Simplified Configuration - Concise syntax instead of verbose component field specifications
4. API Consistency - Matches existing strictKnownMarketplaces syntax (these parameters already exist for marketplace sources)
5. Cache Optimization - Could cache only the subdirectory contents instead of entire repository

Implementation Behavior:

When path is specified:

1. Clone the git repository
2. Navigate to the specified subdirectory
3. Look for .claude-plugin/ in that subdirectory (or use strict: false)
4. Cache only the subdirectory contents (optimization)

When ref is specified:

1. Clone/checkout the specified git reference
2. Use that version of the plugin
3. Track the ref for updates

Alternative Solutions

Workaround 1: Component Configuration Fields (Current)

{
  "source": {
    "source": "github",
    "repo": "org/plugin-repo"
  },
  "strict": false,
  "commands": ["./plugin/commands/"],
  "agents": ["./plugin/agents/"],
  "skills": ["./plugin/skills/"],
  "mcpServers": "./plugin/.mcp.json"
}

Limitations:

• Verbose and error-prone (must list every component type)
• Entire repository still cloned
• Still causes development environment pollution (.mcp.json at any level is loaded)
• No version control support
• Easy to miss a component type

Workaround 2: Monorepo Approach

marketplace-repo/
└── plugins/
    ├── plugin-1/
    ├── plugin-2/
    └── plugin-3/

Limitations:

• Forces all plugins into one repository
• Complex version management (all-or-nothing)
• Can't have per-plugin development workflows
• Doesn't solve development environment pollution

Workaround 3: Plugin at Repository Root

plugin-repo/
├── .claude-plugin/
├── commands/
├── agents/
└── README.md

Limitations:

• Entire repo is just the plugin
• Can't have substantial development infrastructure
• No space for tests, build tools, documentation
• Inflexible structure

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Real-World Scenario: Multi-Cloud Infrastructure Plugin Ecosystem

1. Setup: I'm building a Terraform plugin ecosystem with separate plugins for AWS, GCP, Azure, and a core standards plugin. Each needs its own repository with:

• Plugin files in a plugin/ subdirectory
• Development infrastructure (tests, build scripts, documentation) in repo root
• Different release cycles and versions

1. Current Problem:

• When I launch Claude Code in my terraform-aws-plugin repo to develop/test the plugin, Claude Code automatically loads the plugin's .mcp.json file
• This pollutes my development session with MCP servers meant for plugin users, not plugin developers
• I have to either:
• Move the plugin to repo root (limiting dev infrastructure)
• Use verbose component field configuration (error-prone)
• Accept the pollution (confusing development experience)

1. With This Feature:

Marketplace configuration:

{
  "plugins": [
    {
      "name": "terraform-core",
      "source": {
        "url": "https://gitea.internal.company.com/iac/terraform-core.git",
        "ref": "v1.2.0",
        "path": "plugin"
      }
    },
    {
      "name": "terraform-aws",
      "source": {
        "url": "https://gitea.internal.company.com/iac/terraform-aws.git",
        "ref": "v2.1.3",
        "path": "plugin"
      }
    },
    {
      "name": "terraform-gcp-beta",
      "source": {
        "url": "https://gitea.internal.company.com/iac/terraform-gcp.git",
        "ref": "develop",
        "path": "plugin"
      }
    }
  ]
}

Repository structure:

terraform-aws-plugin/
├── plugin/                    # Clean plugin code - only this distributed
│   ├── .claude-plugin/
│   ├── commands/
│   ├── agents/
│   ├── skills/
│   └── .mcp.json             # Only loaded when plugin is installed
├── src/                       # Development utilities
├── tests/                     # Test infrastructure
├── docs/                      # Documentation
└── README.md

1. Benefits:

• Clean development environment: plugin's .mcp.json doesn't interfere with dev sessions
• Version control: production uses v2.1.3, testing uses develop branch
• Simple configuration: just path parameter instead of listing all component types
• Optimized: only plugin/ subdirectory cached, not entire repo
• Self-hosted: works with our internal Gitea server

1. Time Saved:

• No more manually specifying all component paths
• No more fighting with MCP server conflicts during development
• Easy testing of pre-release versions alongside stable
• Quick rollback by changing ref parameter

Additional Context

API Consistency:

The ref and path parameters already exist for marketplace sources in strictKnownMarketplaces. This feature request simply extends the same syntax to plugin sources.

From Settings Documentation:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/plugins",
      "ref": "main",
      "path": "marketplace"
    },
    {
      "source": "git",
      "url": "https://gitlab.com/plugins.git",
      "ref": "v3.1",
      "path": "approved"
    }
  ]
}

API Parity Comparison:

| Feature | Marketplace Sources | Plugin Sources | Status |
|---------|-------------------|----------------|--------|
| source | ✅ Supported | ✅ Supported | Parity |
| repo / url | ✅ Supported | ✅ Supported | Parity |
| ref | ✅ Supported | ❌ Missing | Gap |
| path | ✅ Supported | ❌ Missing | Gap |

Related Issues:

• #10238 - Subdirectory support for skills (related but different scope)
• #11243, #11278 - Path resolution bugs for local marketplaces

Expected Outcome:

After implementing this feature:

• ✅ Clean separation between plugin code and development infrastructure
• ✅ No development environment pollution (.mcp.json conflicts eliminated)
• ✅ Version control for individual plugins
• ✅ Flexible repository architecture
• ✅ Consistency with existing marketplace source API
• ✅ Self-hosted git server support (Gitea, GitLab, Bitbucket)
• ✅ Optimized caching behavior
• ✅ Simplified marketplace.json configuration

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

{
  "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"
  }
}

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

// "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
})