/maintaining-a-marketplace

name: maintaining-a-marketplace
description: Use when creating, releasing, or maintaining a Claude Code Plugin Marketplace - covers marketplace.json schema, version management, release checklists, changelog conventions, and validation to prevent sync drift between plugin.json and marketplace.json

Maintaining a Marketplace

Overview

A Claude Code Plugin Marketplace is a git repository containing `.claude-plugin/marketplace.json` that catalogs plugins for discovery and installation. The primary maintenance challenge is **sync drift** — keeping versions, descriptions, and metadata consistent across `plugin.json`, `marketplace.json`, and `CHANGELOG.md`.

When to Use

• Setting up a new marketplace from scratch
• Releasing a new plugin version
• Adding a plugin to an existing marketplace
• Auditing marketplace consistency
• Troubleshooting plugin installation failures

Marketplace Structure

my-marketplace/
  .claude-plugin/
    marketplace.json       # Required: marketplace catalog
  plugins/
    plugin-a/
      .claude-plugin/
        plugin.json        # Required: plugin manifest
      skills/
      commands/
      agents/
    plugin-b/
      .claude-plugin/
        plugin.json

marketplace.json Schema

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Brief marketplace description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "What this plugin does",
      "version": "1.0.0",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      },
      "license": "MIT",
      "keywords": ["category1", "category2"],
      "category": "development"
    }
  ]
}

**Required fields:**

• `name` — Kebab-case marketplace identifier. Users see this: `/plugin install my-tool@marketplace-name`
• `owner.name` — Maintainer name (string, not bare string for owner)
• `plugins` — Array of plugin entries

**Each plugin entry requires:**

• `name` — Kebab-case plugin identifier
• `source` — Where to fetch the plugin (see Source Formats below)

**Common optional fields:** `description`, `version`, `author`, `license`, `keywords`, `category`, `tags`, `homepage`, `repository`

**Fields that DO NOT exist** (do not invent these): `displayName`, `installUrl`, `path`, `marketplace` (as wrapper object)

Source Formats

// Relative path (monorepo — only works with git-based marketplace add)
"source": "./plugins/my-plugin"

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

// GitHub with pinned version
"source": { "source": "github", "repo": "owner/repo", "ref": "v2.0.0", "sha": "a1b2c3..." }

// Git URL (GitLab, Bitbucket, self-hosted)
"source": { "source": "url", "url": "https://gitlab.com/team/plugin.git" }

Release Checklist

When releasing a new plugin version, update these files **in this order**:

1. **`plugins/<name>/.claude-plugin/plugin.json`** — Bump `version` 2. **`.claude-plugin/marketplace.json`** — Update matching plugin entry's `version` to the same value 3. **`CHANGELOG.md`** — Add entry at the top (after `# Changelog` heading) 4. **Validate** — Run `claude plugin validate .` or `/plugin validate .` from the marketplace root 5. **Commit and push** — Single commit with all three file changes

Changelog Format

## plugin-name X.Y.Z

Brief description of the release (1-2 sentences).

**New:**
- Specific new features or additions

**Changed:**
- Modifications to existing behavior

**Fixed:**
- Bug fixes

Only include sections that apply. Be specific — "Added `code-review-checklist` skill for systematic code review" not "Added new skill."

Version Sync Verification

After editing, verify these match:

• `plugins/<name>/.claude-plugin/plugin.json` → `version`
• `.claude-plugin/marketplace.json` → plugin entry's `version`
• `CHANGELOG.md` → entry header `## plugin-name X.Y.Z`

All three MUST show the same version string.

Creating a New Marketplace

From Scratch

1. Create directory structure with `.claude-plugin/marketplace.json` 2. Add plugin entries with `name` and `source` at minimum 3. Add `$schema` field for validation 4. Validate: `claude plugin validate .` 5. Test locally: `/plugin marketplace add ./my-marketplace` 6. Push to git host for distribution

Adding a Plugin to Existing Marketplace

1. Read the plugin's `plugin.json` to extract metadata 2. Add entry to `plugins` array in `marketplace.json` with fields matching plugin.json 3. Validate: `claude plugin validate .` 4. Add changelog entry for the marketplace update

Distribution

Users add your marketplace by its git location:

# GitHub
/plugin marketplace add owner/repo

# Other git hosts
/plugin marketplace add https://gitlab.com/company/plugins.git

# Specific branch/tag
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

# Local (development)
/plugin marketplace add ./my-marketplace

Users install plugins from your marketplace:

/plugin install plugin-name@marketplace-name

Auto-Updates

• Official Anthropic marketplaces auto-update by default
• Third-party marketplaces have auto-update **disabled** by default
• Users toggle auto-update per marketplace in `/plugin` → Marketplaces tab

Team Configuration

Add to `.claude/settings.json` in a project repo to prompt team members to install:

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

Private Repositories

Manual install uses existing git credential helpers. For background auto-updates, set environment tokens:

| Provider | Variables | |---------