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": "[e-mail]"
  },
  "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": "[e-mail]"
      },
      "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
GitHub	GITHUB_TOKEN or GH_TOKEN
GitLab	GITLAB_TOKEN or GL_TOKEN
Bitbucket	BITBUCKET_TOKEN

Common Mistakes

Mistake	Symptom	Fix
Version drift between plugin.json and marketplace.json	Old version installed despite push	Verify both files show same version
Skipping validation	JSON syntax errors, missing fields	Run claude plugin validate . before every push
Generic changelog entries	Users can't evaluate upgrade value	Describe specific changes, name affected skills/agents
Inventing schema fields	Validation errors, plugins not found	Only use fields from the schema above
Using owner as string	Validation error	owner must be object: {"name": "...", "email": "..."}
Missing source in plugin entry	Plugin can't be installed	Every plugin entry needs source
Relative paths in URL-based marketplace	"path not found" errors	Only use relative paths with git-based marketplace add
Not committing all sync files together	Partial release, version mismatch	Single commit for plugin.json + marketplace.json + CHANGELOG.md
Forgetting to push	Local changes, users see old version	Commit AND push after release

Quick Reference

Task	Files to Touch
New plugin version	plugin.json + marketplace.json + CHANGELOG.md
New plugin added	marketplace.json + CHANGELOG.md
New marketplace	.claude-plugin/marketplace.json only
Description update	plugin.json + marketplace.json (keep in sync)
Validate	claude plugin validate . or /plugin validate .