| name | claude-md-hygiene |
| version | 1.0.0 |
| description | Audit and enforce the CLAUDE.md discipline rubric introduced in
stharrold-templates v8.9. Finds low-value stub files, oversized
CLAUDE.md files, and dated section headers; reports actionable
cleanup suggestions; optionally fails CI when thresholds are
exceeded.
Use when: starting work on CLAUDE.md files, before tagging a
release, or as a periodic docs-hygiene check in CI.
Triggers: audit CLAUDE.md, lint CLAUDE.md, find CLAUDE.md stubs,
check CLAUDE.md discipline
Outputs: a report listing files by category (stubs, oversized,
dated, clean) and their line counts. Exits non-zero when
thresholds are exceeded.
|
Quick Reference
uv run python .claude/skills/claude-md-hygiene/scripts/audit_claude_md.py
uv run python .claude/skills/claude-md-hygiene/scripts/audit_claude_md.py --strict
uv run python .claude/skills/claude-md-hygiene/scripts/audit_claude_md.py --root src/
Why this skill exists
The anti-pattern this skill catches was discovered during the synavistra
session in early 2026: stharrold-templates used to auto-generate a
type: claude-context frontmatter stub in every directory that matched
a hardcoded TARGET_DIRS list. Every one of these stubs was functionally
equivalent to ls -- it listed the subdirectories below it, declared a
purpose, and linked to its parent. None of them carried non-obvious
facts. They cost context tokens in every Claude Code session that
navigated near them and misled users into thinking there was useful
reference content where there was none.
The cleanup deleted 17 stubs from synavistra and 22 from the template
itself, plus 4 generator scripts and the claude-md-frontmatter
pre-commit hook that enforced the pattern. This skill is the
replacement: instead of enforcing a frontmatter schema on every file,
it scores each CLAUDE.md by content density and flags the ones that
don't earn their keep.
The rubric (enforced by this skill)
A CLAUDE.md file should:
- Earn its existence with non-obvious content. Entries should cost
someone >30 minutes to rediscover if deleted.
- Stay under 500 lines. Longer files are unscannable during a
session; split into
docs/architecture.md or per-subsystem files.
- Have no dated section headers (
(2026-04-02), (updated ...)).
Git blame is the canonical answer to "when".
- Have no autogenerated Tier-B stub pattern (
## Contents followed
by subdirectory listing; ## Related Documentation auto-footer;
type: claude-context frontmatter without accompanying content).
- Not duplicate facts available in
SKILL.md, README.md, CHANGELOG.md,
or the code itself.
Audit output format
The script prints a report in four sections:
=== claude-md-hygiene audit ===
[STUBS] 3 files match the Tier-B stub pattern:
tests/contract/CLAUDE.md (31 lines)
...
[OVERSIZED] 2 files exceed 500 lines:
.claude/skills/initialize-repository/CLAUDE.md (1045 lines)
...
[DATED] 1 file has a dated section header:
CLAUDE.md:126 ## Pipeline Inference Stack (2026-04-02)
[CLEAN] 4 files pass all checks:
src/assets/pipeline/CLAUDE.md (9 lines)
...
Total: 10 files scanned, 6 issues.
In --strict mode the script exits 1 if any file is in [STUBS] or
[OVERSIZED]. [DATED] is a warning, not a failure (dated headers
are sometimes useful for release announcements).
When to run it
- Before tagging a release (as the last step in your
s3-release flow)
- Periodically in CI (e.g. weekly via
security-audit.yml)
- Interactively when you're about to write a new CLAUDE.md and want
to see whether an existing file should be trimmed or split instead
Related
workflow-utilities -- sibling skill. The deleted generate_claude_md.py
/ check_claude_md_frontmatter.py scripts used to live there.- Root CLAUDE.md "What goes here" rubric -- the editorial policy this
skill enforces.
- synavistra commit
6ab55a0 -- the downstream-driven cleanup that
established the rubric.
