---
slug: "grading-claude-agents-md-agentic-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/SpillwaveSolutions/grading-claude-agents-md-agentic-skill@main/README.md"
repo: "https://github.com/SpillwaveSolutions/grading-claude-agents-md-agentic-skill"
source_file: "README.md"
branch: "main"
---
# Grading Claude Agents MD

Grades and improves CLAUDE.md (Claude Code) and AGENTS.md (Codex/OpenCode) configuration files.

## Installation

Clone this repository to your Claude skills directory:

```bash
cd ~/.claude/skills
git clone https://github.com/SpillwaveSolutions/grading-claude-agents-md-agentic-skill.git
```

## Usage

### Slash Command

```
/grade-config                    # Grade all config files found
/grade-config --file CLAUDE.md   # Grade specific file
/grade-config --fix              # Auto-fix issues on approval
```

### Natural Language

This skill also activates when you ask Claude to:

- 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
- Audit my config files

## Features

- Grades config files against a 100-point rubric
- Measures file size (lines, bytes, tokens)
- Identifies issues with prioritized fixes
- Automatically implements improvements on approval
- Supports both CLAUDE.md and AGENTS.md formats
- Provides before/after comparison

## Grading Scale

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

## Rubric Categories

- **Structure (25 pts)**: Organization, hierarchy, TOC usage
- **Content Quality (25 pts)**: Clarity, actionability, examples
- **PDA Implementation (25 pts)**: Progressive disclosure, @imports
- **Maintainability (25 pts)**: File size, modularity, updates

## Plugin Structure

```
grading-claude-agents-md-agentic-skill/
├── .claude-plugin/
│   └── marketplace.json
├── skills/
│   └── grading-claude-agents-md/
│       ├── SKILL.md
│       ├── references/
│       │   ├── rubric.md
│       │   ├── improvement-patterns.md
│       │   └── size-guide.md
│       └── templates/
│           └── grade-report.md
├── commands/
│   └── grade-config.md
└── README.md
```

## License

MIT License - see LICENSE file for details.

## Author

Richard Hightower (rick@spillwave.com)