health-check（健康检查）

/health:check

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

Context

• Current project:!pwd
• Project settings exists:!find.claude -maxdepth 1 -name 'settings.json'
• Local settings exists:!find.claude -maxdepth 1 -name 'settings.local.json'

Parameters

Parse these from $ARGUMENTS:

Scope semantics:

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.

1a. Core environment scripts

bash "${CLAUDE_SKILL_DIR}/scripts/check-plugins.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-settings.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-hooks.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-mcp.sh" --home-dir "$HOME" --project-dir "$(pwd)"

Parse STATUS= and ISSUES: from each. Pass --verbose when set on $ARGUMENTS.

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.

1. Locate the SessionStart hook command from .claude/settings.json (look for the command field).
2. If a script is found, run: CLAUDE_CODE_REMOTE=true bash <script-path> Capture exit code. Expected: 0.
3. Run again to verify idempotency — expected: 0.
4. Run with remote guard off: CLAUDE_CODE_REMOTE=false bash <script-path> Expected: 0 (typically a no-op).
5. 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

1c. Pre-commit config validator

If .pre-commit-config.yaml exists:

pre-commit validate-config .pre-commit-config.yaml

Report:

• OK: exits 0 (config is valid)
• WARN: pre-commit not installed — skip check, suggest pip install pre-commit
• ERROR: exits non-zero — show validation error

1d. Permissions coverage check

Compare tools referenced in project files against permissions.allow in .claude/settings.json.

1. Read permissions.allow from .claude/settings.json. Extract the command prefix from each Bash(<prefix>:*) entry.
2. Scan these files for tool invocations:

- justfile / Justfile — commands on recipe lines - Makefile — shell commands on recipe lines - .pre-commit-config.yaml — entry: fields

1. For each tool found in project files:

- Flag as MISSING if no matching Bash(<tool>:*) entry exists in permissions.allow

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

1. Read .claude/settings.json.
2. Check that extraKnownMarketplaces.claude-plugins exists with source.repo = "laurigates/claude-plugins".
3. Check that enabledPlugins contains at least one @claude-plugins entry.
4. Report:

- OK: Both checks pass - WARN: enabledPlugins is empty or missing (marketplace enrolled but no plugins enabled) - ERROR: extraKnownMarketplaces is missing (run /configure:claude-plugins --fix to add it)

Step 2: Run scope-specific audits

For --scope=registry or all:

bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/check-registry.sh" \
  --home-dir "$HOME" --project-dir "$(pwd)"

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

Step 3: Report findings

Print a consolidated report grouped by scope:

1. Environment — plugins/settings/hooks/MCP status + counts, SessionStart smoke test, pre-commit validity, permissions coverage, marketplace enrollment
2. Registry — orphaned projectPath entries, stale enabledPlugins keys, registry-vs-settings drift
3. Stack — detected stack + relevant/irrelevant/missing plugin recommendations
4. Agentic — skills missing optimisation tables, bare CLI commands, stale reviews

Use STATUS= indicators (OK/WARN/ERROR) and issue counts per scope. Include a summary table:

See REFERENCE.md for the full report template.

Step 4: Apply fixes (if --fix)

If --fix is set:

1. 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).
2. 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)
3. Parse each script's output (STATUS=, REMOVED_COUNT=, MESSAGE=, RESTART_REQUIRED=) and report what changed.
4. 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.

Agentic Optimizations

Known Issues