health-plugins

Original：🇺🇸 English

Translated

Diagnose and fix plugin registry issues including orphaned entries and project-scope conflicts (addresses Claude Code issue

1installs

Sourcelaurigates/claude-plugins

Added on2026-02-22

NPX Install

npx skill4agent add laurigates/claude-plugins health-plugins

SKILL.md Content

View Translation Comparison →

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

Plugin registry exists: !

find ~/.claude/plugins -maxdepth 1 -name 'installed_plugins.json' 2>/dev/null

Project settings exists: !

find . -maxdepth 1 -name '.claude/settings.json' 2>/dev/null

Project plugins dir: !

find . -maxdepth 1 -type d -name \'.claude-plugin\' 2>/dev/null

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

json

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