health-plugins

/health:plugins

Diagnose and fix issues with the Claude Code plugin registry. This command specifically addresses issue #14202 where project-scoped plugins incorrectly appear as globally installed.

When to Use This Skill

Use this skill when...	Use another approach when...
Fixing plugin registry corruption (issue #14202)	Comprehensive health check (use /health:check)
Diagnosing project-scope vs global plugin issues	Auditing plugins for relevance (use /health:audit)
Cleaning up orphaned plugin entries	Settings validation only needed
Resolving "plugin already installed" errors	Agentic optimization audit (use /health:agentic-audit)
Manually inspecting registry JSON	Just viewing installed plugins (read registry file)

Context

• Current project: !pwd
• Current project has plugins: !find . -maxdepth 2 -path '*/.claude-plugin/plugin.json' -type f
• Project settings exists: !find . -maxdepth 1 -name '.claude/settings.json'
• Project plugins dir: !find . -maxdepth 1 -type d -name \'.claude-plugin\'

Background: Issue #14202

When a plugin is installed with --scope project in one project, other projects incorrectly show the plugin as "(installed)" in the Marketplaces view. This happens because:

1. The plugin registry at ~/.claude/plugins/installed_plugins.json stores projectPath for project-scoped installs
2. The Marketplaces view only checks if a plugin key exists, not whether it's installed for the current project
3. The install command refuses to install because it thinks the plugin already exists

Impact: Users cannot install the same plugin across multiple projects with project-scope isolation.

Parameters

Parameter	Description
--fix	Apply fixes to the plugin registry
--dry-run	Show what would be fixed without making changes
--plugin <name>	Check/fix a specific plugin only

Execution

Execute this plugin registry diagnostic:

Step 1: Read the plugin registry

1. Read ~/.claude/plugins/installed_plugins.json
2. Parse each plugin entry to extract: plugin name and source, whether it has a projectPath (project-scoped), and the installation timestamp and version

Step 2: Identify issues in the registry

Check for these issue types:

Issue Type	Detection	Severity
Orphaned projectPath	projectPath directory doesn't exist	WARN
Missing from current project	Plugin has different projectPath than current directory	INFO
Duplicate scopes	Same plugin installed both globally and per-project	WARN
Invalid entry	Missing required fields or malformed data	ERROR

Step 3: Report findings

Print a structured diagnostic report listing all installed plugins with scope and status, followed by issues found with severity, details, and suggested fixes.

Step 4: Apply fixes (if --fix flag)

For each issue, apply the appropriate fix:

1. Orphaned projectPath -- remove the orphaned entry from installed_plugins.json
2. Plugin needed in current project -- ask user which plugins to install, add new entry with current projectPath, update .claude/settings.json with enabledPlugins if needed

Before making changes:

1. Create backup: ~/.claude/plugins/installed_plugins.json.backup
2. Validate JSON after modifications
3. Report what was changed

Step 5: Verify the fix

After applying fixes:

1. Re-read the registry
2. Confirm issues are resolved
3. Remind user to restart Claude Code for changes to take effect

Registry Structure Reference

{
  "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"
      }
    ]
  }
}

Scope types:

• "scope": "project" — has projectPath, only active in that project
• "scope": "user" — no projectPath, active globally

Manual Workaround

If automatic fix fails, users can manually edit ~/.claude/plugins/installed_plugins.json:

1. Open the file in an editor
2. Find the plugin entry
3. Either:
   • Remove projectPath to make it global
   • Change projectPath to current project path
   • Add a new entry with different key for current project
4. Save and restart Claude Code

Agentic Optimizations

Context	Command
Plugin registry diagnostics	/health:plugins
Fix registry issues	/health:plugins --fix
Dry-run mode	/health:plugins --dry-run
Inspect registry	jq '.' ~/.claude/plugins/installed_plugins.json 2>/dev/null
Check specific plugin	jq '.["plugin-name"]' ~/.claude/plugins/installed_plugins.json 2>/dev/null
List orphaned paths	jq -r 'to_entries[] | select(.value.projectPath? and (.value.projectPath | test("."))) | .value.projectPath' ~/.claude/plugins/installed_plugins.json 2>/dev/null

Flags

Flag	Description
--fix	Apply fixes (with confirmation prompts)
--dry-run	Show what would be fixed without changes
--plugin <name>	Target a specific plugin

See Also

• /health:check - Full diagnostic scan
• /health:settings - Settings file validation
• Issue #14202 - Upstream bug report