Claude Marketplace Setup

Claude Code Marketplace Setup

Overview

A Claude Code marketplace is a GitHub repo with .claude-plugin/marketplace.json. Without it the repo is a single installable plugin (all-or-nothing). With it, users register it as a named source and install individual plugins from it.

Two Models

Single Plugin (Simple)

Add .claude-plugin/marketplace.json:

{
  "name": "my-marketplace",
  "id": "my-marketplace",
  "owner": { "name": "username" },
  "metadata": { "description": "...", "version": "1.0.0" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./",
      "description": "...",
      "version": "1.0.0",
      "author": { "name": "..." },
      "keywords": [],
      "category": "workflow"
    }
  ]
}

The existing .claude-plugin/plugin.json defines what gets installed.

Multi-Plugin (Selective Install)

Directory Structure

.claude-plugin/
├── plugin.json         (marketplace-level descriptor)
└── marketplace.json    (lists all installable plugins)

plugins/
├── skill-a/
│   ├── .claude-plugin/plugin.json
│   └── skills/skill-a/SKILL.md
├── skill-b/
│   ├── .claude-plugin/plugin.json
│   └── skills/skill-b/SKILL.md
└── my-command/
    ├── .claude-plugin/plugin.json   ← must have "commands": "./commands"
    └── commands/my-command.md

Per-Plugin plugin.json

{
  "name": "skill-a",
  "version": "1.0.0",
  "description": "...",
  "author": { "name": "..." },
  "license": "MIT"
}

For a commands-only plugin, add "commands": "./commands".

marketplace.json with Multiple Plugins

{
  "plugins": [
    { "name": "skill-a", "source": "./plugins/skill-a", "description": "...", "version": "1.0.0", "author": { "name": "..." }, "keywords": [], "category": "workflow" },
    { "name": "my-command", "source": "./plugins/my-command", "description": "...", "version": "1.0.0", "author": { "name": "..." }, "keywords": [], "category": "workflow" }
  ]
}

Moving Tracked Files

Use git mv to preserve history when reorganizing:

mkdir -p plugins/skill-a/skills plugins/skill-a/.claude-plugin
git mv skills/skill-a plugins/skill-a/skills/skill-a
git mv .agents/commands/my-command.md plugins/my-command/commands/my-command.md

README.md

Update the repo's README.md to document how to install from the marketplace. Include:

1. How to add the marketplace as a source
2. The list of available plugins with one-line descriptions
3. How to install individual plugins

Example:

## Installation

Add as a Claude Code marketplace:

\`\`\`sh
claude plugins add-marketplace username/repo-name
\`\`\`

## Available Plugins

| Plugin | Description |
|--------|-------------|
| `skill-a` | What it does |
| `my-command` | What it does |

Install a plugin:

\`\`\`sh
claude plugins install repo-name/skill-a
\`\`\`

Common Mistakes