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

1. Detect config files: Look for CLAUDE.md and/or AGENTS.md in project
2. Grade each file: Apply rubric from references/rubric.md
3. Generate report: Score card + prioritized issues + improvement plan
4. On approval: Implement changes using references/improvement-patterns.md
5. 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:

1. Backup: Copy original to CLAUDE.md.backup
2. Create structure: Add subdirectory configs if needed
3. Extract content: Move sections to reference files
4. Add TOC: Generate table of contents for files >100 lines
5. Update imports: Add @imports for extracted content
6. Validate: Run size check on new structure
7. 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