--- 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?