Claude Code Marketplace Builder

What is a Marketplace?

A marketplace is a collection of Claude Code plugins that can be shared as a cohesive unit. Marketplaces enable:

• Centralized distribution of multiple related plugins

• Version control and sharing via git repositories

• Team-wide or community-wide plugin discovery

• Organized collections of plugins by theme, team, or purpose

Marketplace Directory Structure

A marketplace follows this structure:

my-marketplace/ ├── .claude-plugin/ │ └── marketplace.json # Marketplace manifest (REQUIRED) ├── plugin-one/ │ └── .claude-plugin/ │ └── plugin.json # Individual plugin manifest ├── plugin-two/ │ └── .claude-plugin/ │ └── plugin.json └── README.md # Documentation (recommended)

Key Points

• Marketplace manifest must be at .claude-plugin/marketplace.json in the marketplace root

• Each plugin within the marketplace has its own plugin.json manifest

• Plugins can be in any subdirectory structure you prefer

• Git version control is recommended for sharing and collaboration

Marketplace Manifest (marketplace.json)

Location and Requirements

The marketplace manifest MUST be located at:

.claude-plugin/marketplace.json

This file defines the marketplace metadata and lists all available plugins.

Required Fields

{ "name": "my-marketplace", "owner": { "name": "Your Name" }, "plugins": [] }

Field Descriptions:

• name : Marketplace identifier in kebab-case (e.g., "team-tools", "data-science-plugins")

• owner.name : Maintainer's name (REQUIRED)

• owner.email : Maintainer's email (OPTIONAL)

• plugins : Array of plugin entries (can be empty initially)

Optional Metadata Fields

{ "name": "my-marketplace", "description": "Marketplace description", "version": "1.0.0", "owner": { "name": "Your Name", "email": "you@example.com" }, "homepage": "https://github.com/username/marketplace", "plugins": [] }

Additional Fields:

• description : Brief overview of the marketplace's purpose

• version : Marketplace version (semantic versioning)

• homepage : URL to marketplace documentation or repository

Adding Plugins to Marketplace

Plugin Entry Structure

Each plugin in the plugins array requires:

{ "plugins": [ { "name": "plugin-name", "source": "./plugin-directory", "description": "Brief description" } ] }

Plugin Entry Fields:

• name : Plugin identifier (MUST match the plugin's plugin.json name)

• source : Path or URL to plugin (see Plugin Sources section)

• description : Brief description (optional but recommended for discoverability)

Example with Multiple Plugins

{ "name": "team-productivity", "owner": { "name": "Engineering Team" }, "description": "Productivity tools for our engineering team", "plugins": [ { "name": "code-review-helper", "source": "./code-review-helper", "description": "Automated code review assistance" }, { "name": "pr-templates", "source": "./pr-templates", "description": "Standardized PR templates and workflows" }, { "name": "testing-utils", "source": "./testing-utils", "description": "Test generation and coverage tools" } ] }

Plugin Sources

Plugin sources in marketplace.json support multiple formats:

Local Path (Relative)

{ "name": "local-plugin", "source": "./local-plugin" }

Use for plugins stored within the marketplace directory. Paths must be relative to the marketplace root.

GitHub Repository

{ "name": "github-plugin", "source": "github:username/repo" }

Use for plugins hosted on GitHub. Claude Code will clone the repository.

Git URL

{ "name": "git-plugin", "source": "https://github.com/username/repo.git" }

Use for plugins hosted on any Git provider. Full git URLs are supported.

Mixed Sources Example

{ "plugins": [ { "name": "internal-tool", "source": "./internal-tool", "description": "Internal team tool" }, { "name": "community-plugin", "source": "github:community/awesome-plugin", "description": "Community-maintained plugin" }, { "name": "external-tool", "source": "https://gitlab.com/team/tool.git", "description": "External Git repository" } ] }

Creating a Marketplace: Step-by-Step

Step 1: Create Marketplace Directory

mkdir my-marketplace cd my-marketplace

Step 2: Create Marketplace Manifest

mkdir .claude-plugin

Create .claude-plugin/marketplace.json :

{ "name": "my-marketplace", "owner": { "name": "Your Name" }, "plugins": [] }

Step 3: Initialize Git (Recommended)

git init

Version control enables:

• Easy sharing via repository URL

• Version history tracking

• Collaboration workflows

• Distribution to users

Step 4: Add Plugins

For each plugin you want to include:

Create plugin directory:

mkdir my-plugin mkdir my-plugin/.claude-plugin

Create plugin manifest (my-plugin/.claude-plugin/plugin.json):

{ "name": "my-plugin", "version": "1.0.0", "description": "Plugin description" }

Add plugin components (skills, commands, agents, etc.)

Update marketplace.json:

{ "plugins": [ { "name": "my-plugin", "source": "./my-plugin", "description": "Plugin description" } ] }

Step 5: Test Locally

Add marketplace to Claude Code:

/plugin marketplace add /path/to/my-marketplace

Install and test plugins:

/plugin install my-plugin@my-marketplace

Verify installation:

• Run /plugin to see installed plugins

• Check /help for new commands

• Test plugin functionality

Local Development Workflow

Testing Changes

When modifying plugins in your marketplace:

Uninstall old version:

/plugin uninstall plugin-name@marketplace-name

Reinstall updated version:

/plugin install plugin-name@marketplace-name

Alternatively, restart Claude Code to reload all plugins.

Development Iteration

Recommended workflow:

• Make changes to plugin files

• Uninstall → Reinstall plugin

• Test functionality

• Commit changes to git

• Repeat as needed

Debugging

Use debug mode to troubleshoot:

claude --debug

This shows:

• Marketplace loading status

• Plugin loading status

• Manifest validation errors

• Component registration

• Any warnings or errors

Distribution and Sharing

Sharing Your Marketplace

Commit to git:

git add . git commit -m "Add marketplace with plugins"

Push to remote repository:

git remote add origin <repository-url> git push -u origin main

Share with users: Users add your marketplace:

/plugin marketplace add <repository-url>

Or for local paths:

/plugin marketplace add /path/to/marketplace

Install plugins:

/plugin install plugin-name@marketplace-name

Managing Plugin Lifecycle

Users can manage installed plugins:

Enable plugin

/plugin enable plugin-name@marketplace-name

Disable plugin

/plugin disable plugin-name@marketplace-name

Uninstall plugin

/plugin uninstall plugin-name@marketplace-name

Testing Checklist

Before distributing your marketplace:

• marketplace.json has required fields (name, owner, plugins)

• All plugin entries have name and source

• Plugin names match their plugin.json names

• Local plugin paths are relative and start with ./

• All plugins install without errors

• Tested with claude --debug for warnings

• README.md documents marketplace purpose and plugins

• Repository is properly initialized with git

• All changes are committed

Best Practices

For comprehensive best practices on organization, versioning, distribution, and collaboration, see reference/best-practices.md .

Key Takeaways

Marketplace Essentials

• Marketplace manifest MUST be at .claude-plugin/marketplace.json (not root)

• Each plugin entry needs name , source , and optionally description

• Plugin sources can be local paths (./plugin ), GitHub repos (github:user/repo ), or Git URLs

• Add marketplace once: /plugin marketplace add <path-or-url>

• Install plugins: /plugin install plugin-name@marketplace-name

Development Workflow

• Create marketplace directory with .claude-plugin/marketplace.json

• Add plugins with their own plugin.json manifests

• Test locally before sharing: /plugin marketplace add /local/path

• Use git for version control and distribution

• Update workflow: uninstall → reinstall or restart Claude Code

Distribution

• Share via git repository URL or local path

• Users add marketplace, then browse/install plugins

• Marketplace can mix local and remote plugin sources

• Use semantic versioning for both marketplace and plugins

• Document installation and usage in README

Common Patterns

For detailed examples of personal, team, community, and hybrid marketplace patterns, see reference/best-practices.md .