╭─╮╭──╮
 ╭╯ ╰╯   ╮
 ╰═══════╯
SKILL.md

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