/claude-markdown-health-check

Tracks the live Claude Code spec — thresholds are fetched from the official docs and cached weekly, so the audit never drifts from the product.

A .claude/ ecosystem auditor for Claude Code. One slash command scans your skills, commands, hooks, agents, settings, plugins, and auto-memory — across both the user tree (~/.claude) and the project tree (./.claude) — and prints one flat, prioritized health report.

It finds dead references, weak or mismatched triggers, token bloat, skill-listing-budget overflow, frontmatter violations, dormant skills, failing hooks, drifted permissions, dead memory links, and per-session context bloat.

It reports first and waits. Nothing is edited, moved, or deleted until you reply naming which findings to fix — that autonomy gate is built into the command.

Demo

Demo coming soon. Run /claude-markdown-health-check to see the scorecard and area-grouped findings render in your own terminal.

What it checks

Thresholds — line counts, description caps, budget fractions, hook timeouts — are pulled live from the official Anthropic docs and cached for a week, so the audit tracks the spec instead of hardcoding it.

Severity tiers

• Critical — broken; blocks correct behavior (dead refs, unregistered hooks, budget overflow, dormant-and-expensive skills, broken plugin refs, dead memory links)
• Structural — works but should be reorganized (weak descriptions, orphans, trigger mismatches, never-fired skills, failing hooks, recurring denials)
• Hygiene — cosmetic / token efficiency (over-broad patterns, stale reminders, low cache-hit, unused declared tools)
• Discovery — additive suggestions surfaced from the current session (new rules, patterns, triggers)

The chat report groups findings by area (Skills, Hooks, Settings & Permissions, Memory, References, Plugins, CLAUDE.md, …) under a scorecard, each rendered as a plain-language line with a [must-fix] / [should] / [polish] chip; the canonical tag stays as a trailing machine code (e.g. · DEAD-REF). See references/report-format.md.

Before the report prints, every judgment finding (the heuristic calls — weak descriptions, orphaned guides, stale CLAUDE.md commands, …) passes an evidence-grounding gate:

it survives only if it can be grounded in a quoted artifact on disk (a line, a resolved-or-missing path, a metric), and [must-fix] / [should] findings then carry that proof as an Evidence: locator.

A finding that can't be grounded is downgraded to a non-actionable [OBSERVATION] or dropped — so a naive false positive (flagging a guide that is referenced, or a command that does exist) never reaches the report.

Deterministic scanner findings skip the gate — the script is already the proof. See references/finding-verification.md.

Install

Plugin (recommended)

In Claude Code, add the marketplace and install:

/plugin marketplace add ncoevoet/claude-markdown-health-check
/plugin install claude-markdown-health-check@ncoevoet-health-check

/claude-markdown-health-check is available right away.

Update with /plugin update claude-markdown-health-check@ncoevoet-health-check, remove with /plugin uninstall claude-markdown-health-check@ncoevoet-health-check.

CLI equivalents: claude plugin marketplace add ncoevoet/claude-markdown-health-check then claude plugin install claude-markdown-health-check@ncoevoet-health-check.

The plugin is self-contained — the command resolves its scripts and reference docs from ${CLAUDE_PLUGIN_ROOT}, so make install is not needed.

Manual (make install)

For hacking on the command itself, install it straight into ~/.claude/:

git clone https://github.com/ncoevoet/claude-markdown-health-check.git
cd claude-markdown-health-check
make install

make install copies five things into ~/.claude/:

• commands/claude-markdown-health-check.md → ~/.claude/commands/
• the reference docs → ~/.claude/claude-markdown-health-check/references/
• validate-skills.sh → ~/.claude/commands/scripts/
• scan-graph.sh → ~/.claude/commands/scripts/
• scan-history.sh → ~/.claude/commands/scripts/

make uninstall removes the command and its reference tree. The bundled scripts are left in place — they live in a shared directory and other commands may depend on them.

make smoke-scan refreshes both scan caches and prints their meta blocks — useful for verifying install before running the full audit.

Either install works. As a plugin, the command resolves its scripts and references from ${CLAUDE_PLUGIN_ROOT} (the installed plugin directory), so it is self-contained — no make install step is needed. With make install it falls back to the ~/.claude/ paths the Makefile creates. Pick the plugin for a one-step install, make install for local development on the command.

This command works in Claude Code only — it depends on filesystem access and bash.

Use

Inside Claude Code:

/claude-markdown-health-check

Examples:

/claude-markdown-health-check
/claude-markdown-health-check quick
/claude-markdown-health-check deep
/claude-markdown-health-check --refresh
/claude-markdown-health-check --compress-bodies
/claude-markdown-health-check --window-days=7
/claude-markdown-health-check check that every skill has a Troubleshooting section

The report prints in chat. Reply naming the findings to fix and the command applies them; until then it touches nothing.

Configuration (optional)

Drop a markdown-health-check.json in ~/.claude/ (user defaults) and/or ./.claude/ (project overrides) to make tuning persistent. All keys are optional; a CLI argument always wins over the file. Precedence is CLI > project > user > default.

{ "windowDays": 14, "severityFloor": "should", "skipPhases": [23] }

Full per-key rationale: references/config-keys.md.

How it works — phases

The phase sequence runs flat from 1 to 25, renumbered from the previous 5a / 5b / 5.5 / 7a scheme — see the Migration note below. Phase 26 (Output Styles) was added later; it runs in the scan band and feeds the Phase 24 report like the other scanners.

Migration note

If you previously referred to phases by the old letter scheme, here is the mapping to the new flat 1..25 numbering:

Testing

Two layers, following Anthropic's develop-tests methodology (code-grading is the fastest, most reliable tier — so the bulk is code-graded, and LLM-grading is reserved for the judgment phases):

• Deterministic (code-graded, CI-safe, no API key). Synthetic .claude/ fixture trees under tests/fixtures/<case>/ each plant one defect; the suite runs validate-skills.sh / scan-graph.sh against them and asserts the exact [TAG] set. A clean/ fixture asserts zero findings — the false-positive guard.

  make test              # bash tests/run.sh — anonymization + eval-schema gates, then 54 code-graded cases (177 assertions)
  bash tests/run.sh 02   # run one case / id-prefix (deterministic suite only)
  

  tests/run.sh also runs two release gates first: an anonymization check (no real scanned-project names in the published commands/, tests/fixtures/, README.md — the real blocklist is gitignored, a placeholder ships) and eval-schema validation (validate-evals.sh asserts every case matches the contract before an expensive run is wasted on a malformed one).
• Behavioural (LLM-graded, opt-in, costs tokens). Runs the full /claude-markdown-health-check headless against a fixture to exercise the judgment phases (weak descriptions, thin CLAUDE.md, autonomy-gate compliance) and the evidence-grounding gate — including paired guards (cases 36–41: a referenced guide and a live CLAUDE.md command must not be flagged, while a genuinely-orphaned guide and a missing-script command must still be), graded by an LLM rubric and scored by majority over N runs.

  make evals                            # needs the authenticated `claude` CLI
  HEALTH_CHECK_EVAL_RUNS=3 make evals   # majority vote to smooth LLM noise
  

Cases live in commands/claude-markdown-health-check/evals/*.json (63 cases: 54 grader.method: code + 9 llm-rubric); fixtures in tests/fixtures/.

Tags are the stable machine contract, so the code-graded cases are immune to report-format changes. CI (.github/workflows/ci.yml) runs shellcheck + bash -n + the anonymization gate + eval-schema validation + the deterministic suite on every push; it does not run the token-spending LLM evals. Every real-world miss or false positive should become a new case.

Requirements

• Claude Code CLI
• bash, awk, grep, find, date (defaults on macOS/Linux)
• jq — required for the history-aware and graph phases (plugin integrity, skill usage, hook reliability, etc.); strongly recommended for the existing skill-listing-budget check
• Optional: nproc for parallel JSONL scanning (falls back to 4 workers if absent)
• For development: jq for make test; the authenticated claude CLI for make evals; shellcheck (CI uses it at -S warning)

Layout

commands/
├── claude-markdown-health-check.md          # the slash command (~440 lines, orchestrator)
├── claude-markdown-health-check/
│   ├── references/
│   │   ├── config-keys.md                   # Phase 1 config schema (markdown-health-check.json)
│   │   ├── skill-listing-budget.md          # Phase 6 audit logic
│   │   ├── skill-usage-metrics.md           # Phase 7
│   │   ├── skill-tool-contract.md           # Phase 9
│   │   ├── frontmatter-schema.md            # Phase 10
│   │   ├── agent-frontmatter.md             # Phase 14 — subagent schema
│   │   ├── hook-safety.md                   # Phase 14 — hook script safety
│   │   ├── reference-graph.md               # Phase 11
│   │   ├── claude-md-quality.md             # Phase 12 rubric
│   │   ├── body-compression.md              # Phase 13 logic
│   │   ├── permission-hygiene.md            # Phase 15
│   │   ├── hook-reliability.md              # Phase 16
│   │   ├── cross-session-patterns.md        # Phase 19 + 22
│   │   ├── memory-hygiene.md                # Phase 20
│   │   ├── plugin-integrity.md              # Phase 2
│   │   ├── token-trend.md                   # Phase 23
│   │   ├── output-styles.md                 # Phase 26
│   │   ├── finding-verification.md          # Pre-print evidence-grounding gate (judgment findings)
│   │   ├── report-format.md                 # Phase 24 report rendering — domain map + scorecard
│   │   └── post-report-menu.md              # Phase 25 menu
│   └── evals/                               # data-driven eval cases
│       ├── 01-clean-zero-findings.json … 65-ref-bare-sibling.json  (54 code + 9 LLM)
│       └── README.md                        # eval schema + how to run
└── scripts/
    ├── validate-skills.sh                   # deterministic compliance validator (Phase 5)
    ├── scan-graph.sh                        # static graph scanner (Phases 2, 11, 20, 26)
    ├── scan-history.sh                      # session-log miner (Phases 7, 9, 15, 16, 19, 22, 23)
    ├── validate-evals.sh                    # eval-case schema/contract gate (CI)
    ├── run-evals-headless.sh                # opt-in LLM-graded eval runner
    └── run-evals.sh                         # manual eval runner

tests/                                       # deterministic test suite (dev-only, CI)
├── run.sh                                   # entrypoint → anonymization + eval-schema + scanners
├── check-anonymization.sh                   # release gate: no real names in published artifacts
├── anonymization-blocklist.example.txt      # placeholder blocklist (real one is gitignored)
├── lib.sh                                   # assert helpers + tag extractors
├── test_scripts.sh                          # data-driven runner over evals/*.json
└── fixtures/<case>/.claude/…                # synthetic trees, one planted defect each

.github/workflows/ci.yml                     # shellcheck + bash -n + tests/run.sh (anon + eval-schema + scanners)

All plain Markdown and shell — read, fork, extend.

License

MIT — see LICENSE.