Claude Code health check — scans plugins, settings, hooks, MCP, runtime state, usage telemetry, permissions, marketplace with optional fixes. Use when checking project health or troubleshooting setup.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Claude Code health check — scans plugins, settings, hooks, MCP, runtime state, usage telemetry, permissions, marketplace with optional fixes. Use when checking project health or troubleshooting setup.
Single entry point for Claude Code health diagnostics. Runs environment checks (plugin registry, settings, hooks, MCP servers, SessionStart executability, pre-commit validity, permissions coverage, marketplace enrollment) plus optional deeper audits, and routes --fix to the appropriate internal workflow.
When to Use This Skill
Use this skill when...
Use another approach when...
Running Claude Code diagnostics
Viewing raw settings (use Read on settings.json)
Troubleshooting plugin registry issues
Inspecting marketplace metadata manually
Auditing plugins for project fit
Installing a specific plugin (use /plugin install)
Session-telemetry mining of ~/.claude/projects/*/*.jsonl for never-fired and dormant skills and plugin agents. Read-only, local-leaning (SKIPs when history is insufficient).
all
Environment checks + all five audits
Execution
Execute this diagnostic router. Default scope is all when --scope is not provided.
Step 1: Run environment checks (always)
Environment checks run regardless of --scope. They cover the baseline health of the Claude Code installation and the current project's .claude/ directory.
Parse STATUS= and ISSUES: from each. Pass --verbose when set on $ARGUMENTS.
If check-settings.sh emits PROJECT_DIR_RESOLVED=<path>, the workspace root had no .claude/ but a single nested */.claude/settings.json was found one level down (parent-workspace / monorepo layout). Note the resolved path in the report so the user knows which config was checked. If it emits PROJECT_DIR_HINT=<msg>, surface the hint — multiple nested configs were found and the user should re-run with --project-dir to target one.
1b. SessionStart smoke test
Check whether scripts/install_pkgs.sh (or any script registered in the SessionStart hook in .claude/settings.json) is executable and exits cleanly in both remote and local contexts.
Locate the SessionStart hook command from .claude/settings.json (look for the command field).
If a script is found, run:
CLAUDE_CODE_REMOTE=true bash <script-path>
Capture exit code. Expected: 0.
Run again to verify idempotency — expected: 0.
Run with remote guard off:
CLAUDE_CODE_REMOTE=false bash <script-path>
Expected: 0 (typically a no-op).
Report:
OK: All three exit 0
WARN: Script exists but is not registered in settings.json hook
ERROR: Script exits non-zero, or script referenced in hook does not exist
Compare tools referenced in project files against permissions.allow in .claude/settings.json.
Read permissions.allow from .claude/settings.json. Extract the command prefix from each Bash(<prefix>:*) entry.
Scan these files for tool invocations:
justfile / Justfile — commands on recipe lines
Makefile — shell commands on recipe lines
.pre-commit-config.yaml — entry: fields
For each tool found in project files:
Flag as MISSING if no matching Bash(<tool>:*) entry exists in permissions.allow
For each Bash(<tool>:*) entry in permissions.allow:
Flag as UNUSED if the tool is not found in any project file (informational, not an error)
Scoring:
OK: No missing permissions
WARN: 1–3 missing permissions
ERROR: 4+ missing permissions
1e. Marketplace enrollment check
The local marketplace key (set by claude marketplace add <name>) is user-chosen and varies between installs (commonly laurigates-claude-plugins, sometimes claude-plugins). Identify the marketplace by its stable source.repo, not by a hardcoded local key.
Read .claude/settings.json.
Scan all entries under extraKnownMarketplaces and find the one whose source.repo equals "laurigates/claude-plugins". Capture that entry's key as $MP_KEY.
Check that enabledPlugins contains at least one key with the suffix @$MP_KEY.
Report:
OK: Both checks pass
WARN: enabledPlugins has no @$MP_KEY entries (marketplace enrolled but no plugins enabled)
ERROR: no extraKnownMarketplaces entry with source.repo = laurigates/claude-plugins (run /configure:claude-plugins --fix to add it)
Reference jq snippet (for verification or fix scripts):
MP_KEY=$(jq -r '.extraKnownMarketplaces // {} | to_entries | map(select(.value.source.repo == "laurigates/claude-plugins")) | .[0].key // empty' .claude/settings.json)
if [ -z "$MP_KEY" ]; thenecho"ERROR: no extraKnownMarketplaces entry with source.repo = laurigates/claude-plugins"else
jq -e --arg k "@$MP_KEY"'.enabledPlugins // {} | to_entries | map(select(.key | endswith($k))) | length > 0' .claude/settings.json >/dev/null \
&& echo"OK: marketplace enrolled as $MP_KEY with enabled plugins" \
|| echo"WARN: marketplace $MP_KEY enrolled but no @${MP_KEY} entries in enabledPlugins"fi
Parse STATUS=, PLUGIN_COUNT=, ORPHANED_ENTRIES=, STALE_ENABLED_ENTRIES=, and ISSUES:.
For --scope=stack or all: follow the tech-stack audit steps from the internal health-audit skill (see ${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md and its REFERENCE.md).
For --scope=agentic or all: follow the skill-quality audit steps from the internal health-agentic-audit skill (see ${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md and its REFERENCE.md).
Parse STATUS=, RUNTIME_SIZE_BYTES=, PROJECTS_TOTAL=, PROJECTS_DEAD=, GH_PATHS_TOTAL=, GH_PATHS_DEAD=, ORPHAN_DISABLED_MCP=, DUPLICATE_MCP=, CLEANUP_SUGGESTED=, and ISSUES:. Pass --verbose to list every dead path / orphaned server (default is a single rolled-up issue per category to keep output compact).
The runtime scope audits ~/.claude.json — the harness state file that grows with every session and is never auto-pruned. It reports four classes of bloat: dead projects[] keys, dead githubRepoPaths[*] worktree paths, orphaned disabledMcpServers[] entries, and bare-vs-namespaced duplicate MCP names. The audit is read-only: it prints suggested jq filters for the operator to run manually after closing other Claude Code sessions.
Concurrent-write warning. The harness rewrites ~/.claude.json on session end. Before acting on the audit's suggested cleanups, close every other Claude Code session — otherwise the in-memory state of a live session will clobber your edits when it next writes the file. An automated cleanup writer is out of scope for this audit.
Parse STATUS=, HISTORY_AVAILABLE=, TRANSCRIPTS_SCANNED=, SKILLS_ENABLED=, SKILLS_FIRED=, SKILLS_NEVER_FIRED=, SKILLS_DORMANT=, AGENTS_ENABLED=, AGENTS_FIRED=, AGENTS_NEVER_FIRED=, AGENTS_DORMANT=, SCHEMA_DRIFT_SUSPECTED=, and ISSUES:. Pass --verbose to list every never-fired / dormant skill and agent (default rolls each category into one issue line). Pass --window-days N to change the dormancy threshold (default 30).
The usage scope mines local session transcripts (~/.claude/projects/*/*.jsonl) for skill- and agent-invocation recency: never-fired skills/agents (installed but zero invocations in history) and dormant skills/agents (last invoked more than the window ago). Agent invocations are read from Agent/Tasktool_use events keyed by subagent_type. Findings are advisory review candidates, not a delete list — a skill or agent can be correct yet rarely needed (recovery, migration, on-demand subagents gated behind a parent skill). The audit is read-only (no --fix path).
Local-leaning. Session history is local and long-lived, so this scope is near-useless in a remote/web sandbox (a fresh clone has ≤1 transcript). It emits STATUS=SKIP with HISTORY_AVAILABLE=false when there are fewer than two transcripts rather than reporting every skill as never-fired. If TRANSCRIPTS_SCANNED>0 but zero tool calls parse, it emits STATUS=WARN TYPE=schema_drift (the transcript JSON shape changed) instead of a bogus all-never-fired result.
If --scope=all AND findings exist in multiple scopes, use AskUserQuestion to let the user pick which scopes to fix (multi-select: registry, stack, agentic).
For each selected scope, delegate:
Scope
Delegate to
registry
bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" (pass --dry-run when set)
stack
Follow the --fix flow in ${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md (Step 6)
agentic
Follow the --fix flow in ${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md (Step 6)
Parse each script's output (STATUS=, REMOVED_COUNT=, MESSAGE=, RESTART_REQUIRED=) and report what changed.
If any fix reports RESTART_REQUIRED=true, remind the user to restart Claude Code.
Step 5: Verify
Re-run the relevant checks and confirm issue counts have dropped.
