| 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
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
