Health

1---2name: health3description: Invoke when Claude ignores instructions, behaves inconsistently, hooks malfunction, or MCP servers need auditing. Audits the full six-layer config stack and flags issues by severity. Not for debugging code or reviewing PRs.4metadata:5  version: "3.11.0"6---7 8# Health: Audit the Six-Layer Stack9 10Prefix your first line with 🥷 inline, not as its own paragraph.11 12 13Audit the current project's Claude Code setup against the six-layer framework:14`CLAUDE.md → rules → skills → hooks → subagents → verifiers`15 16Find violations. Identify the misaligned layer. Calibrate to project complexity only.17 18**Output language:** Check in order: (1) CLAUDE.md `## Communication` rule (global takes precedence over local); (2) language of the user's recent conversation messages; (3) default English. Apply the detected language to all output.19 20Keep the user informed of progress through the three steps: data collection, analysis, and synthesis.21 22## Step 0: Assess project tier23 24Pick one. Apply only that tier's requirements.25 26| Tier | Signal | What's expected |27|------|--------|-----------------|28| **Simple** | <500 project files, 1 contributor, no CI | CLAUDE.md only; 0–1 skills; no rules/; hooks optional |29| **Standard** | 500–5K project files, small team or CI present | CLAUDE.md + 1–2 rules files; 2–4 skills; basic hooks |30| **Complex** | >5K project files, multi-contributor, multi-language, active CI | Full six-layer setup required |31 32## Step 1: Collect all data33 34Run the data collection script and keep the full output. Do not interpret it yet.35 36```bash37bash "${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/health}/scripts/collect-data.sh"38```39 40The script outputs labeled sections: tier metrics, CLAUDE.md (global + local), settings/hooks/MCP, rules, skill inventory, context budget, conversation signals, and skill security content.41 42Interpretation guardrails before Step 2:43- If `jq` is missing, conversation sections may show `(unavailable)`. Treat that as insufficient data, not a finding.44- If `python3` is missing, MCP/hooks/allowedTools sections may show `(unavailable)`. Do not flag those areas from missing collection.45- If `settings.local.json` is absent, hooks/MCP/allowedTools may be unavailable. That can be normal for global-settings-only projects.46- Conversation sampling is limited and MCP token estimates are directional. Use low confidence when the evidence is thin, and re-check tier manually if generated directories inflated the file count.47 48## Step 1b: MCP Live Check49 50After the bash block completes, test every MCP server from the settings before launching analysis agents.51 52For each server:531. Call one harmless tool from that server with minimal input.542. If the call succeeds: mark `live=yes`.553. If it fails or times out: mark `live=no` and note the exact error.56 57Summarize the results in a short table, for example:58 59```60MCP Live Status:61  server_name    live=yes  (N tools available)62  other_server   live=no   error: connection refused / tool not found / API key invalid63```64 65Include this table in Agent 1's input.66 67**If API keys are required:** look for relevant env var names in the server config (e.g., `XCRAWL_API_KEY`, `OPENAI_API_KEY`). Do not validate the key value. Only note whether the env var is set: `echo $VAR_NAME | head -c 5` (5 chars only, do not print the full key).68 69## Step 2: Analyze with tier-adjusted depth70 71State the collected summary in one sentence (word counts, skills found, conversation files sampled). Confirm the tier. Then route:72 73- **SIMPLE:** Analyze locally from Step 1 data. Do not launch subagents. Prioritize core config checks; skip conversation cross-validation unless evidence is obvious.74- **STANDARD/COMPLEX:** Launch two subagents in parallel with the relevant Step 1 sections pasted inline. Keep them off file paths. Redact all credentials (API keys, tokens, passwords) to `[REDACTED]` before sharing the data.75 76**Fallback:** If either subagent fails (API error, timeout, or empty result), do not abort. Analyze that layer locally from Step 1 data instead and note "(analyzed locally -- subagent unavailable)" in the affected section of the report.77 78### Agent 1 -- Context + Security Audit (uses conversation signals only)79 80Read `agents/inspector-context.md`. Give Agent 1 the sections it needs. Include `CONVERSATION SIGNALS`, not the full `CONVERSATION EXTRACT`, so it can inspect enforcement gaps and context pressure without dragging in the heaviest evidence block.81 82### Agent 2 -- Control + Behavior Audit (uses conversation evidence)83 84Read `agents/inspector-control.md`. Give Agent 2 the sections it needs, including the detected tier.85 86## Step 3: Synthesize and present87 88Aggregate the local analysis and any agent outputs into one report:89 90---91 92**Health Report: {project} ({tier} tier, {file_count} files)**93 94### [PASS] Passing95 96Render a compact table of checks that passed. Include only checks relevant to the detected tier. Limit to 5 rows. Omit rows for checks that have findings.97 98| Check | Detail |99|-------|--------|100| settings.local.json gitignored | ok |101| No nested CLAUDE.md | ok |102| Skill security scan | no flags |103 104### Finding format (mandatory under every severity section)105 106Each finding is **three lines, no prose paragraphs**:107 108```109- [severity] <one-line symptom> ({file}:{line} if known)110  Why: <one-line reason it matters for this tier>111  Action: <exact command, edit, or file path to fix>112```113 114`Action:` must be specific enough to copy-paste or click into: a shell command, an `Edit: path/to/file.md` with the old_string/new_string intent, a `Remove: <key> from <file>`, or a URL to follow. Never write "investigate X", "consider Y", "review Z". If the exact fix is unknown, say so and name the diagnostic command: `Action: run \`<cmd>\` to determine scope, then report back`.115 116### [!] Critical -- fix now117 118Rules violated, missing verification definitions, dangerous allowedTools, MCP overhead >12.5%, required-path `Access denied`, active cache-breakers, and security findings.119 120Example:121- [!] `settings.local.json` committed to git (exposes MCP tokens)122  Why: any leaked token enables remote code execution via installed MCP servers123  Action: `git rm --cached .claude/settings.local.json && echo '.claude/settings.local.json' >> .gitignore && git commit -m "chore: untrack local settings"`124 125### [~] Structural -- fix soon126 127CLAUDE.md content that belongs elsewhere, missing hooks, oversized skill descriptions, single-layer critical rules, model switching, verifier gaps, subagent permission gaps, and skill structural issues.128 129Example:130- [~] CLAUDE.md is 1,842 lines; attention degrades past ~200131  Why: large CLAUDE.md pushes the resolver to miss, and often means rules that belong in `rules/` got inlined132  Action: Move the "Testing" and "Style" sections out into `rules/testing.md` and `rules/style.md`, then shrink CLAUDE.md to a pointer table.133 134### [-] Incremental -- nice to have135 136New patterns to add, outdated items to remove, global vs local placement, context hygiene, HANDOFF.md adoption, skill invoke tuning, and provenance issues.137 138Example:139- [-] 18 one-shot Bash entries in `allowedTools` from prior sessions140  Why: lean allowlist reduces prompt overhead and makes it easier to spot drift141  Action: Open `.claude/settings.local.json` and remove: `Bash(rm:*)`, `Bash(curl:*)`, `Bash(lsof:*)` (only the entries not used in the last 30 days).142 143---144 145If all three issue sections are empty, output one short line in the output language like: `All relevant checks passed. Nothing to fix.`146 147## Non-goals148 149- Never auto-apply fixes without confirmation.150- Never apply complex-tier checks to simple projects.151- Flag issues, do not replace architectural judgment.152 153## Gotchas154 155| What happened | Rule |156|---------------|------|157| Read `settings.json` and missed the local override | Always read `settings.local.json` too; it shadows the committed file |158| Subagent API timeout reported as MCP failure | Check `collect-data.sh` exit before blaming the server; MCP failures come from the live probe, not data collection |159| `collect-data.sh` silently empty on some sections | Verify `python3` / `jq` are on PATH; the script degrades sections rather than hard-failing |160| Reported issues in the wrong language | Honor `CLAUDE.md` Communication rule first; only fall back to the user's recent language when the rule is ambiguous |161| Flagged a hook as broken when it was intentionally noisy | Ask the user before calling a hook "broken"; some hooks are deliberately verbose |162| Treated a disabled MCP server as a failure | Respect `enabled: false` in settings; skip without flagging |163 164**Stop condition:** After the report, ask in the output language:165> "All findings above carry an `Action:` line. Want me to apply them? I can handle each layer separately: global CLAUDE.md / local CLAUDE.md / rules / hooks / skills / MCP."166 167Do not make any edits without explicit confirmation. If a finding's `Action:` is missing or vague, fix the report before asking; the user should never have to ask "what exactly do I do about this?"