---
name: claude-md-improver
description: Audit and improve project instruction files such as AGENTS.md, CLAUDE.md, .agents.local.md, and .claude.local.md. Use when the user asks to check, audit, update, improve, or fix project memory or instruction files.
---

# Project Instruction Improver

Audit, evaluate, and improve project instruction files so future Codex or Claude sessions have concise, current, actionable project context.

This skill can write to instruction files only after presenting a quality report and getting user approval.

## Workflow

### Phase 1: Discovery

Find project instruction files in the repository. Prefer `rg --files`; on Windows, use PowerShell-native commands if needed.

```powershell
rg --files | rg '(^|/)(AGENTS\.md|CLAUDE\.md|\.agents\.local\.md|\.claude\.local\.md)$'
```

File types and locations:

| Type | Location | Purpose |
| --- | --- | --- |
| Codex project root | `./AGENTS.md` | Primary Codex project instructions, usually checked into git |
| Claude project root | `./CLAUDE.md` | Primary Claude Code project context, usually checked into git |
| Local Codex override | `./.agents.local.md` | Personal/local Codex notes, normally gitignored |
| Local Claude override | `./.claude.local.md` | Personal/local Claude notes, normally gitignored |
| Global Codex defaults | `~/.codex/AGENTS.md` | User-wide Codex defaults |
| Global Claude defaults | `~/.claude/CLAUDE.md` | User-wide Claude defaults |
| Nested/package files | `**/AGENTS.md` or `**/CLAUDE.md` | Module-level context in monorepos |

When both `AGENTS.md` and `CLAUDE.md` exist, keep tool-specific rules in the matching file and avoid duplicating generic content unless the user asks for parity.

### Phase 2: Quality Assessment

For each instruction file, evaluate it against [references/quality-criteria.md](references/quality-criteria.md).

Quick checklist:

| Criterion | Weight | Check |
| --- | --- | --- |
| Commands/workflows documented | High | Are build/test/lint/deploy commands present and executable? |
| Architecture clarity | High | Can an agent understand the codebase structure? |
| Non-obvious patterns | Medium | Are gotchas and project-specific quirks documented? |
| Conciseness | Medium | Does every line earn its prompt cost? |
| Currency | High | Does it reflect the current codebase state? |
| Actionability | High | Are instructions concrete, not vague? |

Quality scores:

- A (90-100): Comprehensive, current, actionable
- B (70-89): Good coverage, minor gaps
- C (50-69): Basic info, missing key sections
- D (30-49): Sparse or outdated
- F (0-29): Missing or severely outdated

### Phase 3: Quality Report

Always output the quality report before making updates.

```markdown
## Project Instruction Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment

#### 1. ./AGENTS.md
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
| --- | --- | --- |
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- ...

**Recommended additions:**
- ...
```

### Phase 4: Targeted Updates

After the report, ask for confirmation before editing.

Update guidelines:

1. Propose targeted additions only:
   - Commands or workflows discovered during analysis
   - Gotchas or non-obvious patterns found in code
   - Package relationships that were unclear
   - Testing approaches that work
   - Environment or configuration quirks
2. Keep changes minimal:
   - Do not restate obvious code structure
   - Do not add generic best practices
   - Do not preserve one-off fixes unlikely to recur
   - Prefer one-line notes over long explanations
3. Show diffs:
   - File to update
   - Exact addition or replacement
   - One-line reason this helps future sessions

Diff format:

````markdown
### Update: ./AGENTS.md

**Why:** The build command was missing.

```diff
+ ## Commands
+ `npm run build` - Production build.
```
````

### Phase 5: Apply Updates

After user approval, edit only the approved instruction files. Preserve existing structure and formatting, and do not change unrelated project files.

## Templates

Use [references/templates.md](references/templates.md) as a source of section patterns, adapting `CLAUDE.md` examples to `AGENTS.md` when working in Codex projects.

## Common Issues to Flag

1. Stale commands that no longer work
2. Missing dependencies or setup steps
3. Outdated architecture or deleted paths
4. Missing environment variables or config notes
5. Broken test commands
6. Undocumented gotchas or recurring workflow mistakes

## User Tips

When presenting recommendations, remind users:

- Keep instruction files concise; they become model context.
- Commands should be copy-paste ready.
- Store shared team rules in `AGENTS.md` or `CLAUDE.md`.
- Store personal preferences in local-only files if the project uses them.