NINI
4.7 KiB
name, description
| name | description |
|---|---|
| agents-md-improver | Audit and improve Codex AGENTS.md and AGENTS.override.md files in repositories. Use when the user asks to check, audit, update, improve, fix, optimize, or maintain AGENTS.md files, Codex project instructions, or agent guidance. |
AGENTS.md Improver
Audit, evaluate, and improve Codex instruction files so future Codex sessions get concise, current, actionable project context.
This skill can write to AGENTS.md files. Always present a quality report and proposed diffs before editing. Only apply changes after the user approves the exact target files or has explicitly asked you to apply a specific diff.
Codex Instruction Model
Codex discovers guidance in this order:
- Global scope:
~/.codex/AGENTS.override.mdif present, otherwise~/.codex/AGENTS.md. - Project scope: from the project root toward the current working directory. In each directory, Codex checks
AGENTS.override.md, thenAGENTS.md, then configured fallback names. - Merge order: root guidance appears first; files closer to the current directory appear later and can override earlier guidance.
Use AGENTS.override.md for stronger or more specific overrides. Use AGENTS.md for normal shared guidance.
Workflow
Phase 1: Discovery
Find repository instruction files:
rg --files -g 'AGENTS.md' -g 'AGENTS.override.md'
When the user asks about global defaults too, inspect:
Test-Path "$env:USERPROFILE/.codex/AGENTS.md"
Test-Path "$env:USERPROFILE/.codex/AGENTS.override.md"
Also inspect relevant project files that prove current reality:
- Package or build manifests:
package.json,pyproject.toml,Cargo.toml,go.mod,Makefile,justfile, workflow files. - Repo structure: top-level directories and any nested package boundaries.
- Test and lint configuration.
- Existing
.codex/config.toml, hooks, and project-specific scripts.
Prefer rg and rg --files for search. Use the repo's existing conventions before proposing new sections.
Phase 2: Quality Assessment
For each file, evaluate against references/quality-criteria.md.
Score out of 100:
| Criterion | Points |
|---|---|
| Commands and workflows | 20 |
| Architecture clarity | 20 |
| Non-obvious patterns | 15 |
| Conciseness | 15 |
| Currency | 15 |
| Actionability | 15 |
Grades:
- A: 90-100, comprehensive, current, actionable.
- B: 70-89, good coverage with minor gaps.
- C: 50-69, basic info with important gaps.
- D: 30-49, sparse or outdated.
- F: 0-29, missing or severely outdated.
Phase 3: Quality Report
Always output the report before edits:
## AGENTS.md 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
Propose only changes that help future Codex sessions:
- Real commands or workflows discovered during analysis.
- Current architecture facts that are not obvious from filenames.
- Gotchas, environment quirks, or testing approaches that save rediscovery.
- Repository-specific rules that affect how Codex should edit or verify work.
Avoid:
- Generic best practices.
- Obvious descriptions of self-named classes or directories.
- Verbose explanations where one line is enough.
- One-off fixes unlikely to recur.
- Instructions that contradict higher-priority user or project guidance.
Show every proposed change as a focused diff:
### Update: ./AGENTS.md
**Why:** The repo has a lint command but the current instructions do not mention verification.
```diff
+## Commands
+
+`npm run lint` - Run ESLint before handing off frontend changes.
### Phase 5: Apply Approved Updates
After approval, edit only approved files. Preserve existing structure when it is clear. If a file is mostly placeholder content, replace it with a concise project-specific structure using `references/templates.md`.
Before finalizing, validate:
- Commands exist and are named correctly.
- Paths are real.
- Each addition is project-specific.
- The result stays concise enough to be prompt-friendly.
- Nested `AGENTS.override.md` files do not accidentally hide useful `AGENTS.md` guidance in the same directory.
## References
- `references/quality-criteria.md` - scoring rubric.
- `references/templates.md` - concise AGENTS.md templates.
- `references/update-guidelines.md` - what to add and what to avoid.