From skills
Audit CLAUDE.md files against best practices. Analyzes length, structure, anti-patterns, and generates improvement recommendations with concrete suggestions. Invoke when user says "audit claude.md", "check claude.md", "review claude.md", "improve claude.md".
How this skill is triggered — by the user, by Claude, or both
Slash command
/skills:claudemd-audit [path/to/CLAUDE.md][path/to/CLAUDE.md]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Analyze a CLAUDE.md file against best practices and generate actionable improvement recommendations.
Analyze a CLAUDE.md file against best practices and generate actionable improvement recommendations.
User provides a path to the CLAUDE.md file. If not provided, check ./CLAUDE.md first, then ./.claude/CLAUDE.md.
Read the target file using the Read tool before starting analysis.
Before running checks, determine the file type from its path:
./CLAUDE.md or ./.claude/CLAUDE.md at repository rootmonolith/CLAUDE.md)~/.claude/CLAUDE.md -- personal preferences across all projectsThis affects how certain dimensions are evaluated (noted in each dimension below).
Run ALL checks below against the file content. For each dimension, record: status (pass/warn/fail), details, and recommendation if applicable.
Check if the file covers all three dimensions:
File type adjustments:
Mark each as present/partial/missing/not-applicable. Quote the relevant sections found.
Scan for vague instructions vs concrete ones:
npm test before committing", "use snake_case for database columns"List all vague instructions found and suggest concrete replacements.
Count instructions with emphasis markers: "IMPORTANT", "CRITICAL", "MUST", "NEVER", "ALWAYS" (case-insensitive).
Check for each of the 7 anti-patterns:
Instructions about code style that a linter/formatter should handle: indentation, trailing whitespace, semicolons, bracket style, import ordering. Recommend setting up a Claude Code PostToolUse hook with matcher Edit|Write that runs formatter/linter automatically after each file edit, presenting errors for Claude to fix rather than asking Claude to enforce style rules. LLMs are in-context learners -- if the codebase follows consistent patterns, Claude picks them up without being told.
Narrow, task-specific instructions that only apply to rare scenarios. Signs: very specific file names in constraints, edge-case workarounds, one-off behavior corrections. Recommend moving to rules/ with path scoping or removing.
Signs: generic/boilerplate content, obvious framework knowledge restated, content that looks machine-generated. Flag if detected.
Instructions that say "don't do X" without providing an alternative. List each one and suggest adding alternatives.
Large code blocks, inline schemas, full configuration examples. If over 10 lines of embedded code/content, recommend extracting to a separate file with a path reference. Exception: directory tree blocks (showing project structure) up to 30 lines are acceptable and useful for code orientation -- do not flag these. Prefer pointers to copies -- use path/to/file.ts:120-180 references to canonical sources instead of copied snippets that go stale.
Instructions that restate what Claude already knows from training: how React hooks work, Express middleware patterns, standard Git workflow, common TypeScript features. Recommend removing.
Any API keys, connection strings, passwords, tokens in the file. Flag as CRITICAL security issue.
Claude Code wraps CLAUDE.md with a hidden system reminder: "this context may or may not be relevant to your tasks." When CLAUDE.md contains too many non-universal instructions, Claude may discount the entire file -- not just deprioritize, but outright ignore instructions it deems irrelevant.
File type adjustments:
For root files:
.claude/skills/) or separate docs, not in CLAUDE.md. CLAUDE.md is for persistent universal guidelines..claude/rules/*.md with paths: frontmatter or to docs/ for lazy loadingIf file is over 100 lines or fails the universality check, analyze content clusters and propose a split:
.claude/rules/*.md (path-scoped rules)docs/ or similar (reference material)Example output format:
Proposed structure:
CLAUDE.md (keep ~60 lines)
- project overview (WHAT/WHY)
- build/test commands (HOW)
- universal conventions
.claude/rules/api.md (paths: src/api/**)
- API-specific conventions
- endpoint patterns
.claude/rules/frontend.md (paths: src/components/**)
- component conventions
- styling rules
docs/architecture.md (reference, lazy-load)
- detailed service descriptions
- data flow diagrams
If file uses @path imports:
docs/guide.md" without @ prefix -- Claude reads on demand)If the project appears to be a monorepo (multiple services/packages):
CLAUDE.local.md is used for personal project-specific overrides (should be gitignored)claudeMdExcludes setting in .claude/settings.json to skip irrelevant ancestor filesLook for signs of stale content:
Critical instructions should be at the beginning or end of the file (primacy/recency bias). Check if the most important instructions (build commands, critical constraints) are buried in the middle.
Present results as a structured markdown report:
# CLAUDE.md Audit Report
**File**: <path>
**Lines**: N | **Est. instructions**: N
## Summary
<2-3 sentence overall assessment>
**Audit metrics**: [PASS] N | [WARN] N | [FAIL] N
**Adherence risk**: Low / Medium / High
Adherence risk rules:
- **High**: Length or instruction count FAIL, OR secrets detected, OR universality FAIL, OR 3+ dimensions at FAIL level. Warn: "Claude Code wraps CLAUDE.md with a relevance filter -- at this size/density, Claude may ignore instructions entirely."
- **Medium**: any FAIL in non-critical dimensions, OR 2+ dimensions at WARN level
- **Low**: no FAIL, at most 1 WARN
## Findings Overview
| # | Dimension | Status | Key Issue |
|---|-----------|--------|-----------|
| 1 | Length and Size | [PASS/WARN/FAIL] | <brief> |
| 2 | WHAT-WHY-HOW | [PASS/WARN/FAIL] | <brief> |
| ... | ... | ... | ... |
## Detailed Findings
### [PASS/WARN/FAIL] 1. Length and Size
<findings -- keep PASS sections to 1-2 lines, expand WARN/FAIL with evidence and recommendations>
### [PASS/WARN/FAIL] 2. WHAT-WHY-HOW Coverage
<findings>
... (all 11 dimensions)
## Recommendations (Priority Order)
### Critical (fix now)
1. <recommendation with concrete action>
### Important (fix soon)
1. <recommendation with concrete action>
### Nice to Have
1. <recommendation with concrete action>
## Proposed Improvements
<If progressive disclosure is recommended, show the full proposed structure>
<If specific rewrites are suggested, show before/after examples>
Use these status icons (text only, no emoji):
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub pkarpovich/environment --plugin skills