grading-claude-agents-md
Grades and improves CLAUDE.md (Claude Code) and AGENTS.md (Codex/OpenCode) configuration files. Use when asked to grade, score, evaluate, audit, review, improve, fix, optimize, or refactor agent config files. Triggers on 'grade my CLAUDE.md', 'score my AGENTS.md', 'is my CLAUDE.md too big', 'improve my agent config', 'fix my CLAUDE.md', 'optimize context usage', 'reduce tokens in CLAUDE.md', or 'audit my config files'. Automatically grades both files if present, generates improvement plan, and implements changes on approval.
When & Why to Use This Skill
This Claude skill provides a comprehensive auditing and optimization framework for agent configuration files like CLAUDE.md and AGENTS.md. It automates the process of scoring, refactoring, and improving agent instructions to ensure peak performance, reduced token consumption, and better maintainability for Claude Code and Codex projects.
Use Cases
- Auditing Agent Configs: Automatically evaluate the quality of CLAUDE.md or AGENTS.md files against a professional rubric to identify structural gaps and content weaknesses.
- Context Optimization: Reduce token usage and prevent context bloat by splitting large configuration files into modular sub-directories and implementing @imports.
- Automated Refactoring: Reorganize complex project rules, add Tables of Contents for long files, and move style rules to appropriate linter configs to improve agent focus.
- Performance Benchmarking: Generate detailed grade reports (A-F) with prioritized action plans to systematically upgrade the efficiency of AI agent workflows.
- Maintainability Cleanup: Extract duplicate content and implement standardized patterns for monorepos or multi-package projects to ensure consistent agent behavior.
| name | grading-claude-agents-md |
|---|---|
| description | Grades and improves CLAUDE.md (Claude Code) and AGENTS.md (Codex/OpenCode) configuration files. Use when asked to grade, score, evaluate, audit, review, improve, fix, optimize, or refactor agent config files. Triggers on 'grade my CLAUDE.md', 'score my AGENTS.md', 'is my CLAUDE.md too big', 'improve my agent config', 'fix my CLAUDE.md', 'optimize context usage', 'reduce tokens in CLAUDE.md', or 'audit my config files'. Automatically grades both files if present, generates improvement plan, and implements changes on approval. |
Grading CLAUDE.md and AGENTS.md
Grade agent configuration files, generate improvement plans, and implement fixes.
Workflow
┌─────────────────────────────────────────────────────────────┐
│ 1. GRADE 2. PLAN 3. IMPLEMENT │
│ ───────── ───────── ───────────── │
│ Auto-detect Show issues Apply fixes │
│ files → Score with fixes → on approval → │
│ against rubric prioritized verify result │
└─────────────────────────────────────────────────────────────┘
Quick Start
- Detect config files: Look for CLAUDE.md and/or AGENTS.md in project
- Grade each file: Apply rubric from references/rubric.md
- Generate report: Score card + prioritized issues + improvement plan
- On approval: Implement changes using references/improvement-patterns.md
- Verify: Re-grade to confirm improvements
Grading Checklist
Copy and track progress:
Evaluation Progress:
- [ ] Step 1: Detect CLAUDE.md and AGENTS.md files
- [ ] Step 2: Measure size (lines, bytes, tokens)
- [ ] Step 3: Score Structure (25 pts)
- [ ] Step 4: Score Content Quality (25 pts)
- [ ] Step 5: Score PDA Implementation (25 pts)
- [ ] Step 6: Score Maintainability (25 pts)
- [ ] Step 7: Apply modifiers (±10 pts)
- [ ] Step 8: Generate report with grade
- [ ] Step 9: List improvements with priority
- [ ] Step 10: Ask: "Implement these improvements?"
Score Summary
Base: Structure (25) + Content (25) + PDA (25) + Maintainability (25) = 100 pts Modifiers: ±10 pts for bonuses/penalties Final: Capped at 0-100
| Grade | Score | Meaning |
|---|---|---|
| A | 90-100 | Excellent, minimal changes needed |
| B | 80-89 | Good, minor improvements recommended |
| C | 70-79 | Adequate, notable issues to fix |
| D | 60-69 | Poor, significant refactoring needed |
| F | <60 | Critical, major overhaul required |
Reference Files
| Reference | When to Read |
|---|---|
| references/rubric.md | Scoring all criteria |
| references/improvement-patterns.md | Implementing fixes |
| references/size-guide.md | Understanding thresholds |
Implementation Workflow
After grading, if user approves improvements:
- Backup: Copy original to
CLAUDE.md.backup - Create structure: Add subdirectory configs if needed
- Extract content: Move sections to reference files
- Add TOC: Generate table of contents for files >100 lines
- Update imports: Add @imports for extracted content
- Validate: Run size check on new structure
- Report: Show before/after comparison
What Gets Fixed Automatically
| Issue | Fix Applied |
|---|---|
| File too large (>500 lines) | Split into subdirectory configs or docs/ |
| Missing TOC (>100 lines) | Generate and insert table of contents |
| No @imports for large sections | Extract to docs/*.md, add @imports |
| Style rules in config | Move to linter config, add pointer |
| Negative-only rules | Add "instead use X" alternatives |
| Duplicate content | Consolidate to single location |
| Monorepo without subdirs | Create package-level CLAUDE.md files |
Output Format
Grade report structure:
# Config Grade Report: [filename]
## Score: XX/100 (Grade: X)
| Pillar | Score | Max |
|--------|-------|-----|
| Structure | XX | 25 |
| Content Quality | XX | 25 |
| PDA Implementation | XX | 25 |
| Maintainability | XX | 25 |
| Modifiers | ±X | ±10 |
## Top Issues (prioritized)
1. **[Issue]**: [Description] → [Fix]
Impact: +X pts if fixed
2. **[Issue]**: [Description] → [Fix]
Impact: +X pts if fixed
## Recommended Actions
- [ ] Action 1
- [ ] Action 2
- [ ] Action 3
---
**Implement these improvements? (y/n)**
When Not to Use
Do not use this skill for:
- Creating new skills (use skill-creator)
- General markdown editing
- README.md or documentation files
- System prompts or prompt engineering
- MCP server configuration