---

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

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

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

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