audit-claude-md Skill

Audit and refactor CLAUDE.md files to eliminate bloat, enforce context engineering best practices, and create folder-level CLAUDE.md files for complex domain-specific instructions.

Quick Start

Run the audit command to analyze all CLAUDE.md files:

/audit-claude-md

Or audit a specific file:

/audit-claude-md path/to/CLAUDE.md

What This Audits

Line Count Analysis

Vague Language Detection

Prohibited patterns that degrade LLM instruction-following:

• "should probably" → Use MUST, SHOULD, or MAY
• "might want to" → Be specific or omit
• "you could" → Use imperative voice
• "consider maybe" → Decide and state clearly
• "it's good to" → Use SHOULD or MUST
• "try to" → State the requirement directly

Required Sections

Root CLAUDE.md must have:

• ## WHAT This Is - Purpose and scope
• ## WHY This Approach - Rationale
• ## HOW To Use It - Instructions

Quality Scoring

Grades

• A (80-100): Excellent - Follows best practices
• B (60-79): Good - Minor improvements needed
• C (40-59): Needs Improvement - Significant issues
• F (0-39): Critical - Major refactoring required

Refactoring Recommendations

If Line Count Exceeds Maximum

1. Extract deep-dive content to docs/references/
2. Keep only essential instructions in CLAUDE.md
3. Add links to reference documentation
4. Use progressive disclosure pattern

If High Vague Language Count

Replace uncertain language with strong modals:

• "should probably" → "MUST" or "SHOULD"
• "might want to" → "Consider" or omit
• "you could" → Direct imperative

If Missing WHAT/WHY/HOW

Add the framework structure:

## WHAT This Is
Brief description of purpose and scope.

## WHY This Approach
- Reason 1
- Reason 2

## HOW To Use It
### Quick Start
...

Scripts

• .spec-flow/scripts/bash/audit-claude-md.sh - Comprehensive audit
• .claude/hooks/claude-md-validator.sh - Pre-edit validation hook

Configuration

Rules defined in .spec-flow/config/claude-md-rules.yaml