conventions-improver

name	conventions-improver
description	Audit and improve project conventions files (AGENTS.md, CLAUDE.md, GEMINI.md). Scans for all conventions files, evaluates quality against a scoring rubric, outputs a quality report, then makes targeted improvements with user approval. Use when asked to check, audit, update, or improve AGENTS.md or similar files.
argument-hint	[path or leave blank to scan entire workspace]
user-invocable	true

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:

Type	Location	Purpose
Project root	./AGENTS.md (or CLAUDE.md, GEMINI.md)	Primary project context, shared with team
Package-specific	./packages/*/AGENTS.md	Module-level context in monorepos
Subdirectory	Any nested location	Feature/domain-specific context

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?