name: plugin-registry description: | Understanding Claude Code's plugin registry structure, installation scopes, and common issues. Use when troubleshooting plugin installation problems, understanding why plugins show as installed incorrectly, or manually fixing registry entries. user-invocable: false allowed-tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite created: 2026-02-04 modified: 2026-02-05 reviewed: 2026-02-05

Claude Code Plugin Registry

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

When to Use This Skill

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

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:

Symptoms:

1. Plugin shows "(installed)" checkmark in Marketplaces view
2. /plugin install says "already installed"
3. Plugin doesn't appear in Installed tab for current project
4. 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

1. Read ~/.claude/plugins/installed_plugins.json with the Read tool
2. Back up with cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup
3. Remove the orphaned entry from the plugins object
4. Write the updated JSON with the Write tool

Add Entry for Current Project

1. Read the registry with Read tool
2. Add a new entry to the plugin's array with scope: "project" and current projectPath
3. Write the updated JSON with Write tool

Convert Project-Scoped to User (Global)

1. Read the registry with Read tool
2. Change "scope": "project" to "scope": "user" and remove projectPath
3. 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

1. Plugin shows installed but doesn't work

   • Check if projectPath matches current directory
   • Check .claude/settings.json for enabledPlugins
   • Run /health:plugins for diagnosis

2. Can't install plugin (already installed)

   • Check registry for existing entry
   • Check if entry has different projectPath
   • Use /health:plugins --fix or manual edit

3. Plugin works in one project but not another

   • Likely a project-scoped plugin
   • Need separate registry entry per project
   • Or convert to global scope

4. Registry file is corrupted

   • Restore from backup if available
   • Or delete and reinstall plugins
   • Location: ~/.claude/plugins/installed_plugins.json

Agentic Optimizations

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.