plugin-marketplace-creator

Plugin Marketplace Creator

Create Claude Code plugin marketplaces—catalogs that distribute plugins to teams and communities via GitHub.

Quick Start

1. Run scripts/init_marketplace.py <name> --path <output-dir> to scaffold
2. Edit .claude-plugin/marketplace.json to add plugins
3. Push to GitHub
4. Users install via /plugin marketplace add owner/repo

Marketplace Structure

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json    # Required: marketplace definition
├── plugins/                 # Optional: local plugins
│   └── my-plugin/
│       └── .claude-plugin/
│           └── plugin.json
└── README.md

Plugin Structure with Skills

Plugins containing skills should have this structure:

plugins/my-plugin/
├── .claude-plugin/
│   └── plugin.json      # NO "skills" field - skills are auto-discovered
└── skills/
    └── my-skill/
        └── SKILL.md

Important: Do NOT add a skills field to plugin.json. Skills are automatically discovered from the skills/ directory.

Marketplace JSON Schema

Required Fields

{
  "name": "marketplace-name",
  "owner": {
    "name": "Team Name",
    "email": "team@example.com"
  },
  "plugins": []
}

Optional Metadata

{
  "metadata": {
    "description": "Brief description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  }
}

Reserved Names (cannot use)

claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, life-sciences

Plugin Entry Schema

Field	Type	Required	Description
name	string	Yes	Kebab-case identifier
source	string|object	Yes	Where to fetch plugin
description	string	No	Brief description
version	string	No	Semantic version
author	object	No	{name, email}
category	string	No	For organization
keywords	array	No	Search tags
strict	boolean	No	Require plugin.json (default: true)

Source Types

Local path:

{"source": "./plugins/my-plugin"}

GitHub:

{"source": {"source": "github", "repo": "owner/repo"}}

Git URL:

{"source": {"source": "url", "url": "https://gitlab.com/team/plugin.git"}}

Complete Example

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@company.com"
  },
  "metadata": {
    "description": "Internal development tools",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Auto-format code on save",
      "version": "1.0.0",
      "category": "development"
    },
    {
      "name": "deploy-tools",
      "source": {"source": "github", "repo": "company/deploy-plugin"},
      "description": "Deployment automation",
      "category": "devops"
    }
  ]
}

Team Configuration

Add to project's .claude/settings.json for automatic installation:

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

Scripts

• init_marketplace.py - Create new marketplace with proper structure
• validate_marketplace.py - Validate marketplace.json and plugin sources
• add_plugin.py - Add plugin entries to existing marketplace

Workflow

Creating a New Marketplace

Pre-flight checks (REQUIRED before running init script):

1. Check git config for user identity:

   git config --get user.name
   git config --get user.email
   

2. If either is not set, ASK THE USER for their name and email before proceeding. Use these values with --owner-name and --owner-email flags.

3. Check if target directory already has a git repo:

   ls -la <target-path>/.git 2>/dev/null
   

   If .git exists, do NOT run git init when setting up the repository.

# 1. Initialize (script auto-detects git config for owner info)
python scripts/init_marketplace.py my-marketplace --path ./output

# Or with explicit owner info if git config is not set:
python scripts/init_marketplace.py my-marketplace --path ./output \
  --owner-name "Your Name" --owner-email "you@example.com"

# 2. Validate
python scripts/validate_marketplace.py ./output

# 3. Push to GitHub (skip git init if .git already exists)
cd output
# Only run 'git init' if there's no existing .git directory
git add -A && git commit -m "Initial"
# Create repo on GitHub and push

# 4. Test in Claude Code
# /plugin marketplace add owner/my-marketplace

Adding Plugins

# Add local plugin
python scripts/add_plugin.py ./marketplace --name my-plugin --source ./plugins/my-plugin

# Add GitHub plugin  
python scripts/add_plugin.py ./marketplace --name external --source github:org/repo

Troubleshooting

Marketplace not loading: Verify .claude-plugin/marketplace.json exists at repo root.

Plugin install fails: Check source is accessible. For private repos, ensure authentication.

Team can't see marketplace: Verify extraKnownMarketplaces in .claude/settings.json.

References

• references/plugin-schema.md - Complete plugin.json schema
• references/examples.md - Additional marketplace examples