Analyzes and improves CLAUDE.md or AGENTS.md files for clarity, structure, and effectiveness. Use when the user wants to review, refine, or optimize their agent instruction files.
Evaluates agent instruction files against best practices and provides concrete improvements.
| Section | Purpose | Required |
|---|---|---|
| Identity/Role | Who the agent is, core expertise | Yes |
| Constraints | Hard rules, non-negotiables | Yes |
| Preferences | Soft rules, style guidance | Recommended |
| Workflows | Multi-step procedures | If applicable |
| Examples | Concrete demonstrations | Recommended |
Effective instructions are:
-v flag" not "write tests"Red flags:
Calculate signal-to-noise ratio:
Target: >70% high-signal content.
## Assessment
**File**: [path]
**Lines**: [count]
**Signal density**: [percentage estimate]
### Strengths
- [what's working]
### Issues
| Problem | Location | Severity |
|---------|----------|----------|
| [issue] | [line/section] | High/Med/Low |
### Recommended Structure
[Proposed outline if reorganization needed]
### Specific Rewrites
**Before** (lines X-Y):
[original text]
**After**:
[improved version]
[Repeat for each significant improvement]
Preserve intent - Improve expression, don't change meaning unless explicitly wrong.
Respect existing style - Match the file's voice and formatting conventions.
Prioritize impact - Focus on changes that materially improve agent behavior.
Explain rationale - Each rewrite should include why it's better.