Claude Code Plugin Registry

Expert knowledge for understanding and troubleshooting the Claude Code plugin registry.

When to Use This Skill

Use this skill when... Use something else when...

Plugin shows "installed" but isn't working Setting up new plugins (use /configure:claude-plugins )

Need to understand plugin scopes Configuring plugin permissions (use settings-configuration skill)

Fixing orphaned registry entries Creating workflows with plugins (use github-actions-plugin)

Debugging installation failures

Registry Location

The plugin registry is stored at:

~/.claude/plugins/installed_plugins.json

This file tracks all installed plugins across all projects.

Registry Structure (v2)

{ "version": 2, "plugins": { "plugin-name@marketplace-name": [ { "scope": "project", "projectPath": "/path/to/project", "installPath": "~/.claude/plugins/cache/marketplace/plugin-name/1.0.0", "version": "1.0.0", "installedAt": "2024-01-15T10:30:00Z", "lastUpdated": "2024-01-15T10:30:00Z", "gitCommitSha": "abc123" } ] } }

Each plugin key maps to an array of installations (supporting multiple scopes).

Field Reference

Field Required Description

scope

Yes "project" or "user" (global)

projectPath

project only Directory where plugin is active

installPath

Yes Cache path for installed plugin files

version

Yes Installed version

installedAt

Yes ISO timestamp of installation

lastUpdated

Yes ISO timestamp of last update

gitCommitSha

Yes Git commit of installed version

Installation Scopes

User Scope (global, default)

/plugin install my-plugin@marketplace

• "scope": "user" in registry entry

• No projectPath field

• Available in all projects

Project Scope

/plugin install my-plugin@marketplace --scope project

• "scope": "project" in registry entry

• Has projectPath set to installation directory

• Should only be active in that project

• Bug #14202: Still shows as "installed" in other projects

Known Issue: #14202

Problem: Project-scoped plugins incorrectly appear as globally installed.

Root Cause: Inconsistent projectPath checking:

Operation Checks projectPath? Result

Marketplaces "(installed)" No Shows installed everywhere

/plugin install

No Refuses to install

Installed tab listing Yes Correctly filtered

Symptoms:

• Plugin shows "(installed)" checkmark in Marketplaces view

• /plugin install says "already installed"

• Plugin doesn't appear in Installed tab for current project

• Plugin doesn't actually work in current project

Workaround: Manually edit the registry to add an entry for the current project.

Manual Registry Operations

View Registry

jq . ~/.claude/plugins/installed_plugins.json

List All Plugins

jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json

Find Project-Scoped Plugins

jq '.plugins | to_entries[] | .value[] | select(.scope == "project") | {projectPath, version}' ~/.claude/plugins/installed_plugins.json

Find Orphaned Entries

Use the Read tool to read ~/.claude/plugins/installed_plugins.json , then check each projectPath with test -d .

Backup Registry

cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup

Fixing Registry Issues

Remove Orphaned Entry

• Read ~/.claude/plugins/installed_plugins.json with the Read tool

• Back up with cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup

• Remove the orphaned entry from the plugins object

• Write the updated JSON with the Write tool

Add Entry for Current Project

• Read the registry with Read tool

• Add a new entry to the plugin's array with scope: "project" and current projectPath

• Write the updated JSON with Write tool

Convert Project-Scoped to User (Global)

• Read the registry with Read tool

• Change "scope": "project" to "scope": "user" and remove projectPath

• Write the updated JSON with Write tool

Project Settings Integration

Project-scoped plugins also need entries in .claude/settings.json :

{ "enabledPlugins": [ "plugin-name@marketplace" ] }

Without this, even a correctly registered project-scoped plugin won't load.

Troubleshooting Checklist

Plugin shows installed but doesn't work

• Check if projectPath matches current directory

• Check .claude/settings.json for enabledPlugins

• Run /health:plugins for diagnosis

Can't install plugin (already installed)

• Check registry for existing entry

• Check if entry has different projectPath

• Use /health:plugins --fix or manual edit

Plugin works in one project but not another

• Likely a project-scoped plugin

• Need separate registry entry per project

• Or convert to global scope

Registry file is corrupted

• Restore from backup if available

• Or delete and reinstall plugins

• Location: ~/.claude/plugins/installed_plugins.json

Agentic Optimizations

Context Command

View registry jq -c . ~/.claude/plugins/installed_plugins.json

List plugins jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json

Check specific jq '.plugins."name@market"' ~/.claude/plugins/installed_plugins.json

Project plugins jq '.plugins | to_entries[] | .value[] | select(.scope=="project")' ~/.claude/plugins/installed_plugins.json

Quick Reference

Registry Path

~/.claude/plugins/installed_plugins.json

Key Format

{plugin-name}@{marketplace-name}

Scope Indicator

• "scope": "project"

• projectPath → Project-scoped

• "scope": "user" → Global (user-wide)

After Editing

Always restart Claude Code for registry changes to take effect.