agentleFS
Sign inStart free
marcusgollmarcusgoll/Spec-Flow/.claude/skills/audit-claude-md/SKILL.md

audit-claude-md

Skill94 starsChanged 6 months agoMITView on GitHub

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. Run the audit command to analyze all CLAUDE.md files: Or audit a specific file: 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" →…

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 7
  2. Distinctive:

    Root CLAUDE.md: must have:

    line 41
  3. Distinctive:

    Keep only essential instructions in CLAUDE.md

    line 69
  4. Distinctive:

    Add links to reference documentation

    line 70
  5. Distinctive:

    Use progressive disclosure pattern

    line 71
  6. Distinctive:

    Add the framework structure:

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

File TypeWarningMaximum
Feature CLAUDE.md100 lines200 lines
Project CLAUDE.md150 lines300 lines
Root CLAUDE.md300 lines400 lines

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

ComponentWeight
Line count30%
Vague language25%
Strong modals (MUST/SHOULD/NEVER)15%
Required sections15%
External references10%
Freshness5%

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free