/health:plugins Skill | Agent Skills

/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:

The plugin registry at ~/.claude/plugins/installed_plugins.json stores projectPath for project-scoped installs
The Marketplaces view only checks if a plugin key exists, not whether it's installed for the current project
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

Read ~/.claude/plugins/installed_plugins.json
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:

Orphaned projectPath -- remove the orphaned entry from installed_plugins.json
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:

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

Step 5: Verify the fix

After applying fixes:

Re-read the registry
Confirm issues are resolved
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:

Open the file in an editor
Find the plugin entry
Either:
- Remove projectPath to make it global
- Change projectPath to current project path
- Add a new entry with different key for current project
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 |

Agent Skills: /health:plugins

Install this agent skill to your local

Skill Files