Managing Marketplaces

Overview

Plugin marketplaces are catalogs of available plugins. This skill covers how updates work, caching, and versioning.

Key Locations

~/.claude/plugins/marketplaces/

~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/

~/.claude/plugins/known_marketplaces.json

Update Mechanism

Marketplace Level (No Version Pin)

Marketplaces track main branch HEAD - no commit pinning:

// known_marketplaces.json
{
  "superpowers-marketplace": {
    "source": {
      "source": "git",
      "url": "https://github.com/obra/superpowers-marketplace.git"
    },
    "lastUpdated": "2026-01-09T15:25:06.447Z",
    "autoUpdate": true
  }
}

• autoUpdate: true

  pulls latest on startup/refresh

Plugin Level (Version Pinned)

Plugins ARE versioned via the

version

~/.claude/plugins/cache/
├── superpowers-marketplace/
│   └── superpowers/
│       └── 4.0.3/           ← version from plugin.json
└── claude-plugins-official/
    └── hookify/
        └── e30768372b41/    ← commit hash for official plugins

Update Flow

digraph update_flow {
    rankdir=TB;
    "Claude Code starts" [shape=box];
    "Pull marketplace (git pull main)" [shape=box];
    "Read marketplace.json" [shape=box];
    "For each enabled plugin" [shape=diamond];
    "Check if version cached" [shape=diamond];
    "Use cached version" [shape=box];
    "Fetch plugin from source" [shape=box];
    "Cache at version directory" [shape=box];

    "Claude Code starts" -> "Pull marketplace (git pull main)";
    "Pull marketplace (git pull main)" -> "Read marketplace.json";
    "Read marketplace.json" -> "For each enabled plugin";
    "For each enabled plugin" -> "Check if version cached";
    "Check if version cached" -> "Use cached version" [label="yes"];
    "Check if version cached" -> "Fetch plugin from source" [label="no"];
    "Fetch plugin from source" -> "Cache at version directory";
    "Cache at version directory" -> "For each enabled plugin";
    "Use cached version" -> "For each enabled plugin";
}

Version Pinning Summary

autoUpdate: true

/plugin marketplace update

Commands

# List known marketplaces
/plugin marketplace list

# Update marketplace metadata
/plugin marketplace update <marketplace-name>

# Add marketplace
/plugin marketplace add owner/repo              # GitHub
/plugin marketplace add ./local-path            # Local
/plugin marketplace add https://url.git         # Git URL

# Remove marketplace (also uninstalls plugins from it)
/plugin marketplace remove <marketplace-name>

Local Development

ccd CLI (Recommended)

For marketplaces with a CLI for managing symlinks, use it:

cd ~/projects/my-marketplace
pnpm install
pnpm ccd link activate    # Symlink all plugins (creates cache if needed)
pnpm ccd link review      # Check status
pnpm ccd link deactivate  # Remove symlinks

Run

pnpm ccd --help

Workflow:

1. Activate symlinks:

   pnpm ccd link activate

   (no install required)
2. Develop: edit source, restart CC to see changes
3. Relink after any

   claude plugin install

   (overwrites symlinks)

Manual Symlink Method

For marketplaces without the CLI, manually replace cache with symlinks.

Key insight: Cache path uses marketplace's

name

~/.claude/plugins/cache/<name>/...

# 1. Clone repo locally (if not already)
git clone https://github.com/owner/marketplace ~/projects/my-marketplace

# 2. If not installed, add and install (skip if already from GitHub)
claude plugin marketplace add ~/projects/my-marketplace
claude plugin install my-plugin@my-marketplace

# 3. Replace cache with symlink (works for GitHub or local installs)
rm -rf ~/.claude/plugins/cache/<marketplace-name>/my-plugin/*/
ln -s ~/projects/my-marketplace/plugins/my-plugin \
      ~/.claude/plugins/cache/<marketplace-name>/my-plugin/<version>

Caveats:

• Reinstall overwrites symlink - re-run step 3 after any install
• Session-based reload, not hot-reload in same session

Why this works: CC loads plugins from cache path. Symlink makes cache path point to source. CC follows symlinks transparently.

Standard Method

Official docs show uninstall/reinstall cycle:

/plugin uninstall my-plugin@my-marketplace
/plugin install my-plugin@my-marketplace

Enabling Plugins

In project or user

settings.json

{
  "enabledPlugins": {
    "plugin-name@marketplace-name": true
  }
}

Creating Plugins in a Marketplace

CRITICAL: When creating a new plugin, you MUST do BOTH:

1. Create the plugin directory with

   plugin.json

2. Register the plugin in

   marketplace.json

marketplace/
├── .claude-plugin/
│   └── marketplace.json    ← MUST add entry here
└── plugins/
    └── new-plugin/
        └── plugin.json     ← AND create this

Failure mode: Creating only the directory results in

/doctor

Plugin new-plugin not found in marketplace marketplace-name

Checklist for New Plugin

• Create

  plugins/<name>/plugin.json

  with name, version, description
• Add entry to

  .claude-plugin/marketplace.json

  plugins array
• Entry must include:

  name

  ,

  source

  (e.g.,

  "./plugins/<name>"

  ),

  description

• Run

  /doctor

  to verify no plugin errors

Notes

• Removing a marketplace uninstalls all plugins from it
• Multiple versions can coexist in cache (old versions not auto-cleaned)

• lastUpdated

  timestamp tracks when marketplace was last refreshed