| name | context-review |
| description | Review CLAUDE.md files for quality, efficiency, and structure. Use when auditing LLM context files, checking documentation organization, preparing for context optimization, or ensuring lean imperative instructions. |
| allowed-tools | Read, Grep, Glob |
| context | fork |
| agent | context-doc-agent |
LLM Context Review
Reviews CLAUDE.md and child CLAUDE.md files to ensure they provide
efficient, focused context for AI assistants without token waste.
Overview
This skill analyzes CLAUDE.md files against quality standards defined in
.claude/design/design.config.json and the LLM Context Agent design document.
It checks line counts, content structure, design doc pointers, and
identifies opportunities for improvement.
Instructions
1. Locate Configuration
Read .claude/design/design.config.json to understand quality standards:
- Root CLAUDE.md max lines (default: 500)
- Child CLAUDE.md max lines (default: 300)
- Required design doc pointers setting
- Module structure for monorepos
2. Find CLAUDE.md Files
Search for CLAUDE.md files in the repository:
- Root:
CLAUDE.md or CLAUDE.local.md
- Children:
{module}/CLAUDE.md for each module
- Monorepo packages: Check each package directory
3. Analyze Each File
For each CLAUDE.md file found:
Line Count Check:
- Count total lines (excluding blank lines)
- Compare against limits (root: 500, child: 300)
- Flag files exceeding limits
Content Structure Check:
- Verify high-level imperative instructions (not details)
- Check for design doc pointers using @ syntax or links
- Identify overly detailed sections (candidate for design docs)
- Look for duplicated information between files
Design Doc Pointer Check:
- Find references to design documentation
- Verify @ syntax is used correctly:
@./.claude/design/module/doc.md
- Ensure pointers include guidance on when to load context
- Check that docs being pointed to actually exist
Hierarchy Check:
- Verify child CLAUDE.md files exist where appropriate
- Check for modules with complex docs that should have children
- Identify opportunities to split large root files
4. Generate Report
Create a comprehensive review report with:
Summary:
- Total CLAUDE.md files found
- Average line count
- Files over limit count
- Missing design doc pointers count
Issues by File:
Group by severity (high, medium, low):
- High: Files exceeding line limits by >20%
- High: Missing design doc pointers when design docs exist
- High: Overly detailed sections that should be design docs
- Medium: Files approaching line limits (>80%)
- Medium: No child CLAUDE.md for complex modules
- Low: Minor structure improvements
Recommendations:
Actionable suggestions:
- Which sections to move to design docs
- Where to create child CLAUDE.md files
- How to improve @ syntax pointer clarity
- What duplicated content to consolidate
Example Issue:
### High Priority
CLAUDE.md: 687 lines (limit: 500, 37% over)
- "Testing" section is very detailed (120 lines) → move to design doc
- "Architecture" duplicates content in pkgs/my-package/CLAUDE.md
- Missing pointer to `.claude/design/my-package/architecture.md`
Recommendation:
1. Create `.claude/design/project/testing-strategy.md` for testing details
2. Add pointer: "For testing details → @./.claude/design/project/testing-strategy.md"
3. Remove architecture duplication, keep only pointer to package CLAUDE.md
5. Quality Metrics
Calculate and report:
- Efficiency Score: Percentage of files within limits
- Pointer Coverage: Percentage of design docs with CLAUDE.md pointers
- Hierarchy Health: Appropriate child files for module complexity
- Duplication Level: Amount of repeated content across files
Output Format
Generate markdown report with structure:
# CLAUDE.md Review Report
**Date:** YYYY-MM-DD
**Repository:** {name}
**Type:** {monorepo|single-package}
## Summary
- CLAUDE.md files: X
- Average line count: Y
- Files over limit: Z
- Overall efficiency: N%
## Issues Found
### High Priority
[List of high-priority issues with file locations and recommendations]
### Medium Priority
[List of medium-priority issues]
### Low Priority
[List of low-priority issues]
## Recommendations
1. [Specific actionable recommendation]
2. [Specific actionable recommendation]
...
## Quality Metrics
- Efficiency Score: X%
- Pointer Coverage: Y%
- Hierarchy Health: Z%
- Duplication Level: N%
## Next Steps
[Suggested order of operations to address issues]
Special Cases
Monorepo:
Review both root CLAUDE.md and package-level files. Check for appropriate
delegation between root and children.
No design docs yet:
If .claude/design/ doesn't exist, note that design documentation system
should be set up first.
CLAUDE.local.md:
These override CLAUDE.md and should follow same standards. Review both if
present, noting which takes precedence.
Success Criteria
A good review report:
- Identifies specific line numbers for problematic sections
- Provides concrete recommendations, not vague suggestions
- Prioritizes issues by impact on context efficiency
- Includes actionable next steps in recommended order
