Conventions File Improver

Audit, evaluate, and improve project conventions files (AGENTS.md, CLAUDE.md, GEMINI.md) to ensure AI agents have optimal project context.

This skill can write to conventions files. After presenting a quality report and getting user approval, it applies targeted improvements.

Workflow

Phase 1: Discovery

Find all conventions files in the repository using this priority order: AGENTS.md, then CLAUDE.md, then GEMINI.md.

Search for files named AGENTS.md, CLAUDE.md, or GEMINI.md at the root and in any subdirectories.

File Types & Locations:

Note: AI agents auto-discover conventions files in parent directories, so monorepo setups work automatically.

Phase 2: Quality Assessment

For each conventions file found, evaluate it against the following scoring rubric (total: 100 points):

Scoring Criteria

1. Commands/Workflows (20 points)

• 20: All essential commands documented with context (build, test, lint, deploy, dev)
• 15: Most commands present, some missing context
• 10: Basic commands only, no workflow
• 5: Few commands, many missing
• 0: No commands documented

2. Architecture Clarity (20 points)

• 20: Clear codebase map — key directories explained, module relationships, entry points, data flow
• 15: Good structure overview, minor gaps
• 10: Basic directory listing only
• 5: Vague or incomplete
• 0: No architecture info

3. Non-Obvious Patterns (15 points)

• 15: Gotchas and quirks captured — known issues, workarounds, edge cases, "why we do it this way"
• 10: Some patterns documented
• 5: Minimal pattern documentation
• 0: No patterns or gotchas

4. Conciseness (15 points)

• 15: Dense, valuable content — no filler, no obvious info, no redundancy
• 10: Mostly concise, some padding
• 5: Verbose in places
• 0: Mostly filler or restates obvious code

5. Currency (15 points)

• 15: Reflects current codebase — commands work, file references accurate, tech stack current
• 10: Mostly current, minor staleness
• 5: Several outdated references
• 0: Severely outdated

6. Actionability (15 points)

• 15: Instructions are executable — commands can be copy-pasted, steps concrete, paths real
• 10: Mostly actionable
• 5: Some vague instructions
• 0: Vague or theoretical

Grade thresholds: A (90–100), B (70–89), C (50–69), D (30–49), F (0–29)

Assessment process: Read the file completely, cross-reference with actual codebase (verify commands, check if referenced files exist, test architecture descriptions), score each criterion, then list specific issues and propose concrete improvements.

Red flags to note:

• Commands that would fail (wrong paths, missing deps)
• References to deleted files/folders
• Copy-paste from templates without customization
• "TODO" items never completed
• Duplicate info across multiple conventions files

Phase 3: Quality Report Output

Always output the quality report before making any updates.

## Conventions File Quality Report

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

### File-by-File Assessment

#### 1. ./AGENTS.md (Project Root)
**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:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

Phase 4: Targeted Updates

After outputting the quality report, ask for user confirmation before updating.

Update principles — only add information that genuinely helps future AI sessions:

What TO add:

• Commands or workflows discovered during analysis
• Gotchas or non-obvious patterns found in code
• Package relationships that weren't clear
• Testing approaches that work
• Configuration quirks or environment-specific knowledge

What NOT to add:

• Obvious info restatable from code (e.g., "UserService handles users")
• Generic best practices already covered everywhere
• One-off bug fixes unlikely to recur
• Verbose explanations — prefer one-liners

Diff format for each change — show file path, a Why: explanation, and a unified diff:

### Update: ./AGENTS.md

**Why:** Build command was missing, causing confusion about how to run the project.

+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server |
+| `npm test` | Run test suite |

Phase 5: Apply Updates

After user approval, apply changes using file editing tools. Preserve existing content structure.

Recommended File Structure

Use only the sections relevant to the project. Typical sections:

• Commands — table of build/test/lint/dev commands
• Architecture — directory tree with # purpose annotations
• Key Files — list of entry points and important config paths
• Code Style — project-specific conventions (not generic advice)
• Environment — required env vars and setup steps
• Testing — test commands and patterns
• Gotchas — non-obvious issues, ordering dependencies, common mistakes

What Makes a Great Conventions File

Key principles:

• Concise and human-readable — one line per concept when possible
• Actionable commands that can be copy-pasted
• Project-specific patterns, not generic advice
• Non-obvious gotchas and warnings

Validation checklist before finalizing any update:

• Each addition is project-specific
• No generic advice or obvious info
• Commands are tested and work
• File paths are accurate
• Would a new AI session find this helpful?
• Is this the most concise way to express the info?