| name | context-audit |
| description | Comprehensive quality audit for CLAUDE.md context files. Use when performing thorough quality checks, preparing for releases, ensuring context efficiency, or verifying token optimization. |
| allowed-tools | Read, Glob, Grep, Bash(grep *), Bash(wc *) |
| context | fork |
| agent | context-doc-agent |
LLM Context Comprehensive Audit
Performs deep quality audits of CLAUDE.md context files, checking structure,
content quality, efficiency, design doc references, and compliance with
standards.
Overview
This skill provides comprehensive quality auditing for LLM context files
by running all validation checks, analyzing content efficiency, verifying
design doc pointers, checking word limits, and generating detailed audit
reports with prioritized recommendations.
Quick Start
Audit all context files:
/design-docs:context-audit
Audit specific file:
/design-docs:context-audit CLAUDE.md
Audit package context:
/design-docs:context-audit pkgs/effect-type-registry/CLAUDE.md
Quick audit (non-strict):
/design-docs:context-audit --strict=false
Parameters
Optional
target: Path to CLAUDE.md file or "all" (default: all)strict: Enable strict mode with additional checks (default: true)check-refs: Validate design doc references exist and check pointer content drift (default: true)output: Output file path for audit report
Workflow
High-level audit process:
- Parse parameters to determine audit scope and strictness
- Load design.config.json to get quality standards (word limits, etc.)
- Discover CLAUDE.md files using Glob (root + package-level)
- Run validation checks (structure, formatting, markdown quality)
- Analyze content quality (efficiency, organization, token usage)
- Check design doc pointers (existence, validity, coverage)
- Verify word limits (root: 2000, child: 1000 from config)
- Calculate health scores (file, package, overall)
- Identify issues by severity (critical, high, medium, low)
- Generate recommendations prioritized by impact
- Output audit report with actionable improvements
Instructions
IMPORTANT: Follow the detailed step-by-step instructions in
instructions.md to perform the audit correctly.
For usage examples and common scenarios, see examples.md.
Output Format
The audit generates a structured report with:
Summary Section
- Total files audited
- Overall health score (0-100)
- Critical/high/medium/low issue counts
- Pass/fail status
File-Level Details
For each CLAUDE.md file:
- File path and role (root vs child)
- Word count vs limit
- Structure validation results
- Content quality score
- Design doc pointer status
- Specific issues found
Recommendations
Prioritized list of improvements:
- Critical issues (must fix)
- High priority (should fix)
- Medium priority (nice to have)
- Low priority (optional)
Quality Metrics
- Average word count
- Design doc pointer coverage
- Content efficiency score
- Token optimization score
Success Criteria
The audit passes when:
- All files under word limits (root: 2000, child: 1000)
- No critical or high severity issues
- All design doc pointers valid and exist
- Content is lean imperative instructions (not implementation details)
- Proper separation between root and child contexts
Related Skills
/design-docs:context-validate - Basic structure and formatting validation/design-docs:context-review - Quality and efficiency review/design-docs:context-update - Update context files based on audit findings/design-docs:context-split - Split large files that exceed limits/design-docs:design-audit - Similar comprehensive audit for design docs
