claude-md-hygiene

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

# Report only (exit 0 regardless)
uv run python .claude/skills/claude-md-hygiene/scripts/audit_claude_md.py

# CI mode: fail if any file is >500 lines OR matches the stub template
uv run python .claude/skills/claude-md-hygiene/scripts/audit_claude_md.py --strict

# Limit the scan to a subtree
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:

1. Earn its existence with non-obvious content. Entries should cost someone >30 minutes to rediscover if deleted.
2. Stay under 500 lines. Longer files are unscannable during a session; split into docs/architecture.md or per-subsystem files.
3. Have no dated section headers ((2026-04-02), (updated ...)). Git blame is the canonical answer to "when".
4. Have no autogenerated Tier-B stub pattern (## Contents followed by subdirectory listing; ## Related Documentation auto-footer; type: claude-context frontmatter without accompanying content).
5. 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.