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:

{ "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/ ):

{ "name": "plugin-name", "description": "What this plugin does", "version": "1.0.0" }

Team settings.json (inside .claude/ ):

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

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:

What are you distributing?

• Commands (slash commands)

• Agents (subagents)

• Skills (model-invoked capabilities)

• Hooks (event handlers)

• MCP servers (external tools)

• Mix of the above

How many plugins?

• Single plugin

• Multiple related plugins

• Large plugin collection

Who is the audience?

• Personal use (just me)

• Team (colleagues via git)

• Organization (company-wide)

• Public community

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

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

{ "name": "plugin-name", "description": "Clear description of what this plugin provides", "version": "1.0.0", "author": { "name": "Author Name", "email": "author@example.com" }, "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):

{ "name": "company-tools", "owner": { "name": "Company Name", "email": "team@company.com" }, "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):

{ "name": "community-collection", "owner": { "name": "Community", "email": "maintainers@example.com" }, "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:

/plugin marketplace add ./path-to-marketplace

For Team Distribution

Add to project's .claude/settings.json :

{ "extraKnownMarketplaces": { "team-tools": { "source": { "source": "github", "repo": "company/claude-plugins" } } }, "enabledPlugins": { "formatter@team-tools": true, "linter@team-tools": true } }

How it works:

• Team member clones project

• Claude Code reads .claude/settings.json

• Prompts to trust configured marketplaces

• Prompts to install enabled plugins

• New team members get correct setup automatically

For Public Distribution

Push marketplace repo to GitHub

Document installation in README:

Installation

Add the marketplace:

/plugin marketplace add owner/repo

Install plugins:

/plugin install formatter@owner-tools

For Enterprise

- Set up private git access (SSH keys or tokens)

- Create internal marketplace with git URL sources

- Configure .claude/settings.json
 in project templates

- Document for IT/security review

Phase 6: Validation and Testing

Step 1: Validate JSON Syntax

# Validate marketplace structure
claude plugin validate .

# Manual JSON validation
python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"

Step 2: Test Marketplace Addition

# Add marketplace locally
/plugin marketplace add ./path-to-marketplace

# Verify it appears
/plugin marketplace list

Step 3: Test Plugin Installation

# Browse available plugins
/plugin

# Install a plugin
/plugin install plugin-name@marketplace-name

# Verify components work
/help  # Check commands appear

Step 4: Test Team Flow (if applicable)

- Clone project with settings.json to new location

- Trust folder when prompted

- Verify marketplaces and plugins install correctly

Step 5: Verify All Components

- Commands: Run /command-name
 to test

- Agents: Check /agents
 or try invoking via Task

- Skills: Use trigger terms to activate

- Hooks: Trigger events to test

- MCP servers: Check MCP tool availability

Architecture Patterns

Monorepo Pattern

Structure:

company-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── plugin-a/
│   ├── plugin-b/
│   └── plugin-c/
└── README.md

Pros:

- Single repo to manage

- Unified versioning

- Easy cross-plugin changes

- Simpler CI/CD

Cons:

- All plugins share access control

- Larger repo size

- All-or-nothing updates

Best for: Team tools, related plugins, unified ownership

Multi-Repo Pattern

Structure:

# Marketplace repo
tools-marketplace/
└── .claude-plugin/marketplace.json

# Separate plugin repos
plugin-a/   # github.com/org/plugin-a
plugin-b/   # github.com/org/plugin-b
plugin-c/   # github.com/org/plugin-c

Pros:

- Independent versioning

- Separate access control

- Distributed ownership

- Smaller repos

Cons:

- More repos to manage

- Version coordination needed

- More complex CI/CD

Best for: Community collections, mixed ownership, independent plugins

Hybrid Pattern

Structure:

{
  "plugins": [
    {"name": "core", "source": "./plugins/core"},
    {"name": "community", "source": {"source": "github", "repo": "community/tool"}},
    {"name": "internal", "source": {"source": "git", "url": "https://git.corp/..."}}
  ]
}

Pros:

- Flexibility to mix sources

- Can include community plugins

- Supports private + public

Cons:

- More complex to maintain

- Mixed trust levels

- Varied update cycles

Best for: Enterprise, mature ecosystems, gradual migration

Common Pitfalls

1. Confusing Marketplace with Plugin

Wrong: Thinking marketplace.json IS the plugin
Right: marketplace.json POINTS TO plugins

marketplace.json is a catalog. The actual plugin code lives in separate directories or repos.

2. Wrong Source Type

Wrong: Using GitHub shorthand for private repos

{"source": "github", "repo": "private-org/private-repo"}  // May fail

Right: Use git URL for private repos

{"source": "git", "url": "git@github.com:private-org/private-repo.git"}

3. Missing Required Fields

marketplace.json required:

- name

- owner.name

- plugins
 array

plugin.json required:

- name

- description

- version

4. Path Errors

Wrong: Relative paths from wrong directory

{"source": "../plugins/tool"}  // Relative to what?

Right: Paths relative to marketplace.json location

{"source": "./plugins/tool"}  // Relative to .claude-plugin/

5. Version Mismatch

Keep versions in sync:

- plugin.json
 version

- marketplace.json
 plugin entry version

When you update a plugin, update both files.

6. Forgetting Validation

Always run before publishing:

claude plugin validate .

7. Trust Model Misunderstanding

Users MUST explicitly trust marketplaces. You cannot force-install plugins on team members. The settings.json only PRE-CONFIGURES - users still approve.

When to Use This Skill

Use marketplace-builder when:

- Creating a new marketplace

- Publishing plugins for distribution

- Setting up team-wide plugin configuration

- Converting local plugins to distributable packages

- Troubleshooting marketplace or plugin issues

Don't use when:

- Creating individual commands (use slash-command-builder)

- Creating individual agents (use agent-builder)

- Creating individual skills (use skill-builder)

- Just using existing plugins (use /plugin commands directly)

File Reference

Templates

- templates/basic-marketplace.md
 - Single plugin, simple setup

- templates/plugin-structure.md
 - Complete plugin creation guide

- templates/multi-plugin.md
 - Monorepo pattern

- templates/multi-repo.md
 - Distributed plugins pattern

- templates/enterprise-marketplace.md
 - Enterprise with team config

Examples

- examples/development-tools.md
 - 6 dev tool plugins

- examples/team-workflows.md
 - 6 team workflow plugins

- examples/specialized-domains.md
 - 6 domain-specific plugins

Reference

- reference/syntax-guide.md
 - Complete JSON schemas

- reference/best-practices.md
 - Design principles

- reference/troubleshooting.md
 - Common issues and debugging