---
name: marketplace-builder
description: Create Claude Code plugin marketplaces for distributing plugins via local, GitHub, or git sources. Use when setting up team plugin distribution, organizing multiple plugins, or creating custom marketplace infrastructure. References complete Anthropic documentation.
---

# Marketplace Builder

Build marketplaces that centralize plugin discovery, version management, and team distribution.

## When to Use

- Distributing plugins to your team
- Organizing multiple related plugins
- Setting up custom plugin infrastructure
- Creating GitHub-based plugin marketplaces
- Managing plugin versions and updates

## What Are Marketplaces?

Marketplaces are JSON catalogs that:
- Centralize plugin discovery and installation
- Manage plugin versions and sources
- Support local, GitHub, and git repository sources
- Enable team-wide plugin distribution
- Provide metadata for plugin browsing

**Key benefit**: One marketplace can distribute many plugins with automatic updates.

## Quick Start Workflow

### 1. Create Marketplace Structure

```
my-marketplace/
├── .claude-plugin/
│   └── marketplace.json    # Marketplace manifest (required)
├── plugins/                # Plugin sources (if local)
│   ├── plugin-one/
│   └── plugin-two/
└── README.md               # Documentation (recommended)
```

### 2. Write marketplace.json

```json
{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Marketplace for team Claude Code plugins",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "plugin-one",
      "description": "First plugin description",
      "version": "1.0.0",
      "keywords": ["tag1", "tag2"],
      "source": "./plugins/plugin-one",
      "strict": true
    }
  ]
}
```

### 3. Add Marketplace

**Local path**:
```bash
/plugin marketplace add ./path/to/marketplace
```

**GitHub repository**:
```bash
/plugin marketplace add owner/repo
```

**Git URL**:
```bash
/plugin marketplace add https://gitlab.com/org/marketplace.git
```

### 4. Install Plugins

```bash
/plugin install plugin-one@my-marketplace
```

## Essential Patterns

### Pattern 1: Local Development Marketplace

For testing plugins during development:

```
dev-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── my-skill/
                └── SKILL.md
```

**marketplace.json**:
```json
{
  "name": "dev-marketplace",
  "owner": {"name": "Dev Team"},
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "strict": true
    }
  ]
}
```

**Use when**: Rapid iteration on plugins before distribution.

### Pattern 2: GitHub Marketplace (Recommended for Teams)

Host marketplace in GitHub repository:

```
https://github.com/org/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── plugin-one/
│   ├── plugin-two/
│   └── plugin-three/
└── README.md
```

**marketplace.json**:
```json
{
  "name": "team-plugins",
  "owner": {
    "name": "Organization Name",
    "email": "team@org.com"
  },
  "metadata": {
    "description": "Official Claude Code plugins for our team",
    "version": "2.1.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "plugin-one",
      "description": "Description",
      "version": "1.2.0",
      "source": "./plugins/plugin-one"
    }
  ]
}
```

**Installation**:
```bash
/plugin marketplace add org/claude-plugins
/plugin install plugin-one@team-plugins
```

**Use when**: Team distribution with version control and collaboration.

### Pattern 3: Multiple Source Types

Mix local and remote plugin sources:

```json
{
  "name": "mixed-marketplace",
  "owner": {"name": "Your Name"},
  "plugins": [
    {
      "name": "local-plugin",
      "source": "./plugins/local-plugin"
    },
    {
      "name": "github-plugin",
      "source": {
        "source": "github",
        "repo": "owner/plugin-repo"
      }
    },
    {
      "name": "git-plugin",
      "source": {
        "source": "url",
        "url": "https://gitlab.com/team/plugin.git"
      }
    }
  ]
}
```

**Use when**: Combining internal and external plugins.

### Pattern 4: Missing Manual example

Study this repo as a production-ready marketplace that ships the meta tooling plugin:

```
surf-market/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   └── claude-code-meta/
├── README.md
└── skill-examples/
```

**marketplace.json** (`.claude-plugin/marketplace.json`):
```json
{
  "name": "surf-market",
  "owner": {
    "name": "Artimath",
    "email": "ryan@artimath.dev"
  },
  "metadata": {
    "description": "Personal Claude Code meta tooling marketplace.",
    "version": "0.1.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "claude-code-meta",
      "description": "Meta builders for skills, agents, hooks, plugins, marketplaces, and slash commands.",
      "keywords": ["claude-code", "builders", "meta"],
      "source": "./plugins/claude-code-meta",
      "strict": true
    }
  ]
}
```

**Lessons**:
- Keep scope narrow so the metadata stays easy to manage.
- Bundle example artifacts close to their reference skill for quick inspiration.
- Document what is included so other contributors immediately understand the repo layout.

## Marketplace.json Schema

### Required Fields

**name**: Marketplace identifier (kebab-case)
```json
"name": "my-marketplace"
```

**owner**: Maintainer information
```json
"owner": {
  "name": "Your Name",
  "email": "you@example.com"
}
```

**plugins**: Array of plugin entries
```json
"plugins": [
  {
    "name": "plugin-name",
    "source": "./path/to/plugin"
  }
]
```

### Optional Metadata

```json
"metadata": {
  "description": "Marketplace description",
  "version": "1.0.0",
  "pluginRoot": "./plugins"  // Base path for relative sources
}
```

## Plugin Entry Schema

### Required Fields

**name**: Plugin identifier
```json
"name": "my-plugin"
```

**source**: Plugin location (string or object)
```json
"source": "./plugins/my-plugin"
// or
"source": {
  "source": "github",
  "repo": "owner/plugin-repo"
}
```

### Optional Fields

**Standard metadata**:
```json
{
  "description": "Plugin description",
  "version": "1.0.0",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "homepage": "https://github.com/org/plugin",
  "repository": {
    "type": "git",
    "url": "https://github.com/org/plugin.git"
  },
  "license": "MIT",
  "keywords": ["tag1", "tag2"]
}
```

**Component paths** (if not default):
```json
{
  "commands": "./cmd/",
  "agents": "./agents/",
  "hooks": "./automation/",
  "mcpServers": "./mcp/"
}
```

**strict** (default true):
```json
"strict": true   // Requires plugin.json in plugin folder
"strict": false  // Marketplace entry is complete manifest
```

## Plugin Source Types

### Relative Paths (Same Repository)

```json
{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}
```

Resolves relative to `metadata.pluginRoot` if set, otherwise relative to marketplace.json.

### GitHub Repositories

```json
{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}
```

Fetches from `https://github.com/owner/plugin-repo`.

### Git Repositories

```json
{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}
```

Supports any git hosting service.

## Team Distribution Patterns

### Pattern A: Project Settings (Auto-Install)

Configure in `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {"source": "github", "repo": "org/claude-plugins"}
    }
  }
}
```

Team members trust folder → plugins auto-install.

**Use when**: Mandating team-wide tooling.

### Pattern B: User Settings (Manual Install)

Users add marketplace to `~/.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "personal-market": {
      "source": "./path/to/marketplace"
    }
  }
}
```

**Use when**: Optional or personal tools.

### Pattern C: Command-Line (Ad-Hoc)

```bash
/plugin marketplace add org/claude-plugins
/plugin install plugin-name@marketplace-name
```

**Use when**: Testing or one-off installations.

## Marketplace Commands

**Add marketplace**:
```bash
/plugin marketplace add owner/repo         # GitHub
/plugin marketplace add ./local/path       # Local
/plugin marketplace add https://url.git    # Git
```

**List marketplaces**:
```bash
/plugin marketplace list
```

**Remove marketplace**:
```bash
/plugin marketplace remove marketplace-name
```

**Install from marketplace**:
```bash
/plugin install plugin-name@marketplace-name
```

**Update plugin**:
```bash
/plugin uninstall plugin-name@marketplace-name
/plugin install plugin-name@marketplace-name
```

## Versioning & Updates

**Marketplace versioning**:
```json
"metadata": {
  "version": "2.1.0"
}
```

**Plugin versioning** (in marketplace entry):
```json
{
  "name": "my-plugin",
  "version": "1.2.3",
  "source": "./plugins/my-plugin"
}
```

**Update workflow**:
1. Increment version in marketplace.json
2. Update plugin versions as needed
3. Document changes in CHANGELOG.md
4. Commit and push (if git-based)
5. Users reinstall plugins for updates

## Environment Variables

**CLAUDE_PLUGIN_ROOT**: Available in plugin hooks, resolves to plugin installation directory.

**Use in hook scripts**:
```bash
${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh
```

## Strict Mode

**strict: true** (default):
- Plugin must have `.claude-plugin/plugin.json`
- Marketplace fields supplement plugin.json
- Plugin.json fields take precedence

**strict: false**:
- Marketplace entry is complete manifest
- No plugin.json required
- Use for minimal plugin distribution

## Common Issues

**Marketplace not appearing**:
- Check `.claude-plugin/marketplace.json` exists
- Verify JSON syntax is valid
- Restart Claude Code after adding

**Plugins not installing**:
- Check source paths are correct
- Verify plugin.json exists (if strict: true)
- Test source path resolves correctly

**Version conflicts**:
- Uninstall old version first
- Check marketplace.json has correct version
- Clear cache if needed

**Permission errors**:
- Check file permissions on local paths
- Verify git repository is accessible
- Check GitHub repository visibility

## Complete API Reference

For full marketplace specification including:
- Complete marketplace.json schema
- Plugin source resolution logic
- Team deployment strategies
- Version management patterns
- Git hosting integration
- Custom package manager support

See [references/anthropic-marketplaces-docs.md](references/anthropic-marketplaces-docs.md)

## Related Skills

- **plugin-builder**: Create plugins for marketplaces

## Improving This Skill

Notice gaps, unclear instructions, or better patterns while using this skill?

Use the `continuous-improvement` skill to propose enhancements:
1. Detect the issue
2. Propose specific changes
3. Git branch → commit → surface for approval
4. Update changelog

This skill should evolve with every use.
