marketplace-builder

What this skill does

# Marketplace Builder

A comprehensive guide to creating Claude Code marketplaces and plugins for distributing commands, agents, skills, hooks, and MCP servers.

---

## Quick Reference

### Marketplace vs Plugin Distinction

**Critical concept**: These are NOT the same thing.

| Concept | What It Is | Analogy |
|---------|------------|---------|
| **Marketplace** | JSON catalog listing where plugins live | Library catalog |
| **Plugin** | Packaged collection of components | Book |
| **Components** | Commands, agents, skills, hooks, MCP servers | Chapters |

**Relationship**: One marketplace → many plugins → many components per plugin

**Key insight**: Marketplaces don't HOST plugins. They INDEX them. Plugins can live anywhere (GitHub, GitLab, private git, local paths).

---

### JSON Schema Quick Reference

**Minimal marketplace.json**:
```json
{
  "name": "marketplace-name",
  "owner": {"name": "Owner Name"},
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./path-to-plugin",
      "description": "What this plugin does",
      "version": "1.0.0"
    }
  ]
}
```

**Minimal plugin.json** (inside `.claude-plugin/`):
```json
{
  "name": "plugin-name",
  "description": "What this plugin does",
  "version": "1.0.0"
}
```

**Team settings.json** (inside `.claude/`):
```json
{
  "extraKnownMarketplaces": {
    "marketplace-name": {
      "source": {"source": "github", "repo": "owner/repo"}
    }
  },
  "enabledPlugins": {
    "plugin-name@marketplace-name": true
  }
}
```

---

### Source Types

| Type | Syntax | Best For |
|------|--------|----------|
| **GitHub** | `{"source": "github", "repo": "owner/repo"}` | Public plugins |
| **Git URL** | `{"source": "git", "url": "https://..."}` | Private/GitLab |
| **Directory** | `{"source": "directory", "path": "./path"}` | Monorepo |
| **Relative** | `"./path"` | Shorthand for directory |

---

### Command Reference

```bash
# Add a marketplace
/plugin marketplace add owner/repo
/plugin marketplace add https://gitlab.com/org/repo.git
/plugin marketplace add ./local-marketplace

# List marketplaces
/plugin marketplace list

# Update marketplace catalog
/plugin marketplace update marketplace-name

# Browse and install plugins
/plugin                                    # Interactive browser
/plugin install plugin-name@marketplace    # Direct install

# Manage plugins
/plugin enable plugin@marketplace
/plugin disable plugin@marketplace
/plugin uninstall plugin@marketplace

# Validate structure
claude plugin validate .
```

---

## 6-Phase Workflow

### Phase 1: Requirements Gathering

**Use AskUserQuestion to understand the user's needs:**

1. **What are you distributing?**
   - Commands (slash commands)
   - Agents (subagents)
   - Skills (model-invoked capabilities)
   - Hooks (event handlers)
   - MCP servers (external tools)
   - Mix of the above

2. **How many plugins?**
   - Single plugin
   - Multiple related plugins
   - Large plugin collection

3. **Who is the audience?**
   - Personal use (just me)
   - Team (colleagues via git)
   - Organization (company-wide)
   - Public community

4. **What hosting?**
   - GitHub (public or private)
   - GitLab or other git service
   - Self-hosted git
   - Local development only

**Document the answers before proceeding.**

---

### Phase 2: Architecture Decision

Based on requirements, recommend one of these patterns:

#### Pattern A: Basic Marketplace (Single Plugin)
**Use when**: One plugin, simple distribution
```
my-marketplace/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── commands/
└── agents/
```

#### Pattern B: Monorepo (Multiple Plugins, One Repo)
**Use when**: Related plugins, unified versioning, team ownership
```
company-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── formatter/
│   │   ├── .claude-plugin/plugin.json
│   │   └── commands/
│   ├── linter/
│   │   ├── .claude-plugin/plugin.json
│   │   └── commands/
│   └── tester/
│       ├── .claude-plugin/plugin.json
│       └── agents/
```

#### Pattern C: Multi-Repo (Plugins in Separate Repos)
**Use when**: Independent plugins, different owners, community collection
```
# Marketplace repo
my-marketplace/
└── .claude-plugin/
    └── marketplace.json  # Points to other repos

# Plugin repos (separate)
tool-a/
├── .claude-plugin/plugin.json
└── commands/

tool-b/
├── .claude-plugin/plugin.json
└── agents/
```

#### Pattern D: Enterprise (Hybrid Private + Public)
**Use when**: Mix of internal and external tools, strict access control
```json
{
  "plugins": [
    {"name": "internal-tool", "source": {"source": "git", "url": "https://git.corp/..."}},
    {"name": "community-tool", "source": {"source": "github", "repo": "public/tool"}}
  ]
}
```

**Decision tree**:
- Single plugin? → Pattern A
- Multiple plugins, same team? → Pattern B
- Plugins from different sources? → Pattern C
- Enterprise with private + public? → Pattern D

---

### Phase 3: Plugin Creation

For each plugin, create this structure:

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json         # Required: plugin manifest
├── commands/               # Optional: slash commands
│   └── my-command.md
├── agents/                 # Optional: subagents
│   └── my-agent.md
├── skills/                 # Optional: skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                  # Optional: event handlers
│   └── hooks.json
└── .mcp.json              # Optional: MCP servers
```

**Write plugin.json**:
```json
{
  "name": "plugin-name",
  "description": "Clear description of what this plugin provides",
  "version": "1.0.0",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/owner/repo",
  "license": "MIT"
}
```

**Naming conventions**:
- Plugin name: `kebab-case` (e.g., `code-formatter`)
- Version: Semantic versioning `MAJOR.MINOR.PATCH`
- Commands: `verb-noun.md` (e.g., `format-code.md`)
- Agents: `role-name.md` (e.g., `code-reviewer.md`)

---

### Phase 4: Marketplace Creation

Create `.claude-plugin/marketplace.json`:

**For monorepo (plugins in same repo)**:
```json
{
  "name": "company-tools",
  "owner": {
    "name": "Company Name",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "Company development tools",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "formatter",
      "source": "./plugins/formatter",
      "description": "Code formatting tools",
      "version": "1.0.0"
    },
    {
      "name": "linter",
      "source": "./plugins/linter",
      "description": "Code linting tools",
      "version": "1.0.0"
    }
  ]
}
```

**For multi-repo (plugins in separate repos)**:
```json
{
  "name": "community-collection",
  "owner": {
    "name": "Community",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "tool-a",
      "source": {
        "source": "github",
        "repo": "community/tool-a"
      },
      "description": "Tool A description",
      "version": "2.1.0"
    },
    {
      "name": "tool-b",
      "source": {
        "source": "github",
        "repo": "community/tool-b"
      },
      "description": "Tool B description",
      "version": "1.3.0"
    }
  ]
}
```

---

### Phase 5: Distribution Setup

#### For Personal Use
No additional setup. Add marketplace locally:
```bash
/plugin marketplace add ./path-to-marketplace
```

#### For Team Distribution
Add to project's `.claude/settings.json`:
```json
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "formatter@team-tools": true,
    "linter@team-tools": true
  }
}
```

**How it works**:
1. Team member clones project
2. Claude Code reads `.claude/settings.json`
3. Prompts to trust configured marketplaces
4. Prompts to install enabled plugins
5. New team members ge