Claude Code Plugin Registry Skill

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.

Agent Skills: Claude Code Plugin Registry

Install this agent skill to your local

Skill Files