claude-md-auditor
Use PROACTIVELY when reviewing CLAUDE.md configurations, onboarding new projects, or before committing memory file changes. Validates against official Anthropic documentation, community best practices, and LLM context optimization research. Detects security violations, anti-patterns, and compliance issues. Not for runtime behavior testing or imported file validation.
When & Why to Use This Skill
The claude-md-auditor is a specialized developer tool designed to validate, score, and optimize CLAUDE.md configuration files. It ensures that project memory adheres to official Anthropic documentation, community best practices, and academic research on LLM context optimization. By detecting security vulnerabilities, anti-patterns, and token-heavy structures, it helps maintain a lean and effective context for Claude, preventing performance degradation like the 'lost in the middle' effect.
Use Cases
- Pre-commit Security Auditing: Automatically scan CLAUDE.md files for hardcoded secrets, API keys, or sensitive credentials before they are committed to version control.
- Context Performance Optimization: Refactor memory files using research-based positioning and token budget management to improve Claude's reasoning accuracy and reduce costs.
- CI/CD Integration: Implement automated quality gates in development pipelines to ensure all project repositories maintain high-standard documentation and context configurations.
- Project Onboarding & Troubleshooting: Quickly evaluate the health of a new project's memory hierarchy to identify why an agent might be failing to follow specific standards or instructions.
| name | claude-md-auditor |
|---|---|
| version | 0.2.1 |
| description | Use PROACTIVELY when reviewing CLAUDE.md configurations, onboarding new projects, or before committing memory file changes. Validates against official Anthropic documentation, community best practices, and LLM context optimization research. Detects security violations, anti-patterns, and compliance issues. Not for runtime behavior testing or imported file validation. |
CLAUDE.md Auditor
Validates and scores CLAUDE.md files against three authoritative sources with actionable remediation guidance.
When to Use
- Audit before committing CLAUDE.md changes
- Onboard new projects and validate memory configuration
- Troubleshoot why Claude isn't following standards
- CI/CD integration for automated validation gates
Validation Sources
1. Official Anthropic Guidance
- Memory hierarchy (Enterprise > Project > User)
- "Keep them lean" requirement
- Import syntax and limitations (max 5 hops)
- What NOT to include (secrets, generic content)
- Authority: Highest (requirements from Anthropic)
2. Community Best Practices
- 100-300 line target range
- 80/20 rule (essential vs. supporting content)
- Organizational patterns and maintenance cadence
- Authority: Medium (recommended, not mandatory)
3. Research-Based Optimization
- "Lost in the middle" positioning (Liu et al., 2023)
- Token budget optimization
- Attention pattern considerations
- Authority: Medium (evidence-based)
Output Modes
Mode 1: Audit Report (Default)
Generate comprehensive markdown report:
Audit my CLAUDE.md file using the claude-md-auditor skill.
Output includes:
- Overall health score (0-100)
- Category scores (security, compliance, best practices)
- Findings grouped by severity (CRITICAL → LOW)
- Specific remediation steps with line numbers
Mode 2: JSON Report
Machine-readable format for CI/CD:
Generate JSON audit report for CI pipeline integration.
Use for: Automated quality gates, metrics tracking
Mode 3: Refactored File
Generate production-ready CLAUDE.md:
Audit my CLAUDE.md and generate a refactored version following best practices.
Output: CLAUDE_refactored.md with optimal structure and research-based positioning
Quick Examples
Security-Focused Audit
Run a security-focused audit on my CLAUDE.md to check for secrets.
Checks for: API keys, tokens, passwords, connection strings, private keys
Multi-Tier Audit
Audit CLAUDE.md files in my project hierarchy (Enterprise, Project, User tiers).
Checks each tier and reports conflicts between them.
Score Interpretation
Overall Health (0-100):
- 90-100: Excellent (minor optimizations only)
- 75-89: Good (some improvements recommended)
- 60-74: Fair (schedule improvements)
- 40-59: Poor (significant issues)
- 0-39: Critical (immediate action required)
Category Targets:
- Security: 100 (any issue is critical)
- Official Compliance: 80+
- Best Practices: 70+
Finding Severities
- CRITICAL: Security risk (fix immediately)
- HIGH: Compliance issue (fix this sprint)
- MEDIUM: Improvement opportunity (next quarter)
- LOW: Minor optimization (backlog)
Reference Documentation
Detailed validation criteria and integration examples:
reference/official-guidance.md- Complete Anthropic documentation compilationreference/best-practices.md- Community-derived recommendationsreference/research-insights.md- Academic research findingsreference/anti-patterns.md- Catalog of common mistakesreference/ci-cd-integration.md- Pre-commit, GitHub Actions, VS Code examples
Limitations
- Cannot automatically fix security issues (requires manual remediation)
- Cannot test if Claude actually follows the standards
- Cannot validate imported files beyond path existence
- Cannot detect circular imports
Success Criteria
A well-audited CLAUDE.md achieves:
- Security Score: 100/100
- Official Compliance: 80+/100
- Overall Health: 75+/100
- Zero CRITICAL findings
- < 3 HIGH findings
Version: 1.0.0 | Last Updated: 2025-10-26