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](references/rubric.md)
3. Generate report: Score card + prioritized issues + improvement plan
4. On approval: Implement changes using [references/improvement-patterns.md](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

Reference Files

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

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