| name | docs-health |
| description | Audit documentation health — file sizes, nested CLAUDE.md coverage, stale references, skill inventory. Triggers on doc audit, check docs, missing CLAUDE.md, bloated files, documentation drift, stale file references, skill line counts. Use when this capability is needed. |
| metadata | {"author":"air-gapped"} |
Documentation Health Check
Root CLAUDE.md
!wc -l < CLAUDE.md | xargs -I{} echo "Lines: {}"
!wc -c < CLAUDE.md | xargs -I{} echo "Bytes: {}"
Nested CLAUDE.md files
!find internal/ -name CLAUDE.md -exec wc -l {} + 2>/dev/null || echo "None found"
Missing CLAUDE.md (directories with 5+ source files but no CLAUDE.md)
!for dir in internal/*/; do count=$(find "$dir" -maxdepth 1 -name '*.go' ! -name '*_test.go' 2>/dev/null | wc -l); if [ "$count" -ge 5 ] && [ ! -f "$dir/CLAUDE.md" ]; then echo "MISSING: $dir ($count source files)"; fi; done
Skills (lines per SKILL.md)
!wc -l .claude/skills/*/SKILL.md 2>/dev/null
Stale file references in nested CLAUDE.md
!find internal/ -name CLAUDE.md 2>/dev/null | while read cmd; do dir=$(dirname "$cmd"); grep -oE '[a-z_]+\.go' "$cmd" 2>/dev/null | sort -u | while read f; do if [ ! -f "$dir/$f" ]; then echo "STALE: $cmd references $f (not found)"; fi; done; done
Guidelines
- Root CLAUDE.md: keep under 500 lines
- Nested CLAUDE.md: keep under 100 lines each
- Skills: load on-demand, size less critical but prefer <150 lines with references/
- If "MISSING" appears above, create a CLAUDE.md for that directory
- If "STALE" appears above, fix the reference or remove it
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
