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

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:

1. Registry location, validity, and plugin counts (total / global / project-scoped)
2. Orphaned entries (projectPath directory missing) with severity and suggested fix
3. Plugins enabled in settings but not in the registry
4. 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:

1. Confirm with the user (via AskUserQuestion) which orphaned plugins to remove, unless --dry-run is also set.

2. 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.

3. Parse STATUS=, REMOVED=, REMOVED_COUNT=, and BACKUP_PATH= lines to report what changed.

4. Surface durability warnings. If the output includes SETTINGS_CHEZMOI_MANAGED=true, relay the WARNING= line to the user: the edited ~/.claude/settings.json is chezmoi-managed, so the fix reverts on the next chezmoi apply unless the same key is also removed from the chezmoi source (printed as SETTINGS_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:

1. Add a new entry to .claude/settings.json under enabledPlugins using the Edit tool.
2. Remind the user to run /plugin install via 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" — 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
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