Grading CLAUDE.md and AGENTS.md

Grade agent configuration files, generate improvement plans, and implement fixes.

Workflow

code

┌─────────────────────────────────────────────────────────────┐
│  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:

code

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:

markdown

# 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