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.

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

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:

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

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

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 get correct setup automatically

For Public Distribution

1. •

   Push marketplace repo to GitHub

2. •

   Document installation in README:

   markdown

   ## Installation
   
   Add the marketplace:
   ```bash
   /plugin marketplace add owner/repo
   

   Install plugins:

   bash

   /plugin install formatter@owner-tools
   

   code

For Enterprise

1. •Set up private git access (SSH keys or tokens)
2. •Create internal marketplace with git URL sources
3. •Configure .claude/settings.json in project templates
4. •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)

1. •Clone project with settings.json to new location
2. •Trust folder when prompted
3. •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