From health-plugin
Troubleshoots Claude Code plugin registry issues like installation scopes, orphaned entries, project-scoped visibility bugs, and debugging failures. Details structure of ~/.claude/plugins/installed_plugins.json.
npx claudepluginhub laurigates/claude-plugins --plugin health-pluginThis skill is limited to using the following tools:
Expert knowledge for understanding and troubleshooting the Claude Code plugin registry.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Expert knowledge for understanding and troubleshooting the Claude Code plugin registry.
| Use this skill when... | Use something else when... |
|---|---|
| Plugin shows "installed" but isn't working | Setting up new plugins (use /configure:claude-plugins) |
| Need to understand plugin scopes | Configuring plugin permissions (use settings-configuration skill) |
| Fixing orphaned registry entries | Creating workflows with plugins (use github-actions-plugin) |
| Debugging installation failures |
The plugin registry is stored at:
~/.claude/plugins/installed_plugins.json
This file tracks all installed plugins across all projects.
{
"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"
}
]
}
}
Each plugin key maps to an array of installations (supporting multiple scopes).
| Field | Required | Description |
|---|---|---|
scope | Yes | "project" or "user" (global) |
projectPath | project only | Directory where plugin is active |
installPath | Yes | Cache path for installed plugin files |
version | Yes | Installed version |
installedAt | Yes | ISO timestamp of installation |
lastUpdated | Yes | ISO timestamp of last update |
gitCommitSha | Yes | Git commit of installed version |
/plugin install my-plugin@marketplace
"scope": "user" in registry entryprojectPath field/plugin install my-plugin@marketplace --scope project
"scope": "project" in registry entryprojectPath set to installation directoryProblem: Project-scoped plugins incorrectly appear as globally installed.
Root Cause: Inconsistent projectPath checking:
| Operation | Checks projectPath? | Result |
|---|---|---|
| Marketplaces "(installed)" | No | Shows installed everywhere |
/plugin install | No | Refuses to install |
| Installed tab listing | Yes | Correctly filtered |
Symptoms:
/plugin install says "already installed"Workaround: Manually edit the registry to add an entry for the current project.
jq . ~/.claude/plugins/installed_plugins.json
jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json
jq '.plugins | to_entries[] | .value[] | select(.scope == "project") | {projectPath, version}' ~/.claude/plugins/installed_plugins.json
Use the Read tool to read ~/.claude/plugins/installed_plugins.json, then check each projectPath with test -d.
cp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backup
~/.claude/plugins/installed_plugins.json with the Read toolcp ~/.claude/plugins/installed_plugins.json ~/.claude/plugins/installed_plugins.json.backupplugins objectscope: "project" and current projectPath"scope": "project" to "scope": "user" and remove projectPathProject-scoped plugins also need entries in .claude/settings.json:
{
"enabledPlugins": [
"plugin-name@marketplace"
]
}
Without this, even a correctly registered project-scoped plugin won't load.
Plugin shows installed but doesn't work
projectPath matches current directory.claude/settings.json for enabledPlugins/health:plugins for diagnosisCan't install plugin (already installed)
projectPath/health:plugins --fix or manual editPlugin works in one project but not another
Registry file is corrupted
~/.claude/plugins/installed_plugins.json| Context | Command |
|---|---|
| View registry | jq -c . ~/.claude/plugins/installed_plugins.json |
| List plugins | jq -r '.plugins | keys[]' ~/.claude/plugins/installed_plugins.json |
| Check specific | jq '.plugins."name@market"' ~/.claude/plugins/installed_plugins.json |
| Project plugins | jq '.plugins | to_entries[] | .value[] | select(.scope=="project")' ~/.claude/plugins/installed_plugins.json |
~/.claude/plugins/installed_plugins.json
{plugin-name}@{marketplace-name}
"scope": "project" + projectPath → Project-scoped"scope": "user" → Global (user-wide)Always restart Claude Code for registry changes to take effect.