Agentic-AI-Template/plugins/cache/local-personal/claude-md-management/1.0.0/skills/claude-md-improver/SKILL.md

name, description

name	description
claude-md-improver	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.

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.

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.

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

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