health-plugins
Diagnose and fix Claude Code plugin registry corruption — orphaned entries, stale keys, scope conflicts. Use when seeing plugin-already-installed errors or registry drift.
How do I install this agent skill?
npx skills add https://github.com/laurigates/claude-plugins --skill health-pluginsIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
This skill identifies and repairs plugin registry issues. It contains a security vulnerability where plugin names from the local registry are used to build internal commands without proper sanitization. This could allow malformed registry data to cause unintended changes or corruption of configuration files. It also uses environment introspection commands safely.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1/1 file flagged
What does this agent skill do?
/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.jsonstoresprojectPathfor 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
Parse these from $ARGUMENTS:
| 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 by running the scripts below. Pass --plugin <name> through from $ARGUMENTS when specified.
Step 1: Diagnose the registry
bash "${CLAUDE_SKILL_DIR}/scripts/check-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--plugin <name>] [--verbose]
Parse the STATUS=, PLUGIN_COUNT=, ORPHANED_ENTRIES=, and ISSUES: lines from output. The === PLUGINS === section lists each installed plugin with scope, version, source, and projectPath.
Step 2: Report findings
Print a structured diagnostic report summarising:
- Registry location, validity, and plugin counts (total / global / project-scoped)
- Orphaned entries (projectPath directory missing) with severity and suggested fix
- Plugins enabled in settings but not in the registry
- Plugins from other projects (INFO only, shown with
--verbose)
Use the ISSUES: lines as the authoritative list of problems.
Step 3: Apply fixes (if --fix)
If $ARGUMENTS contains --fix:
-
Confirm with the user (via
AskUserQuestion) which orphaned plugins to remove, unless--dry-runis also set. -
Run the fix script:
bash "${CLAUDE_SKILL_DIR}/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--plugin <name>] [--dry-run]The script creates a timestamped backup at
~/.claude/plugins/installed_plugins.json.backup.<UTC-timestamp>before modifying the registry, validates the resulting JSON, and aborts safely on any error. -
Parse
STATUS=,REMOVED=,REMOVED_COUNT=, andBACKUP_PATH=lines to report what changed. -
Surface durability warnings. If the output includes
SETTINGS_CHEZMOI_MANAGED=true, relay theWARNING=line to the user: the edited~/.claude/settings.jsonis chezmoi-managed, so the fix reverts on the nextchezmoi applyunless the same key is also removed from the chezmoi source (printed asSETTINGS_CHEZMOI_SOURCE=).
Step 4: Handle "plugin needed in current project"
When a plugin exists in the registry under a different projectPath and the user wants it available in the current project, use AskUserQuestion to confirm, then:
- Add a new entry to
.claude/settings.jsonunderenabledPluginsusing theEdittool. - Remind the user to run
/plugin installvia the Claude Code UI for proper registry registration.
Step 5: Verify the fix
After applying fixes, re-run Step 1 and confirm the issue count has dropped. Remind the 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"— hasprojectPath, only active in that project"scope": "user"— noprojectPath, 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
projectPathto make it global - Change
projectPathto current project path - Add a new entry with different key for current project
- Remove
- 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 |
| Diagnose only (script) | bash "${CLAUDE_SKILL_DIR}/scripts/check-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" |
| Fix only (script) | bash "${CLAUDE_SKILL_DIR}/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" |
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laurigates/claude-plugins/health-plugins">View health-plugins on skillZs</a>