ed3dai/ed3d-plugins/maintaining-a-marketplace

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:

Common Mistakes

Quick Reference