NINI
152 lines
4.7 KiB
Markdown
152 lines
4.7 KiB
Markdown
---
|
|
name: agents-md-improver
|
|
description: 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:
|
|
|
|
1. Global scope: `~/.codex/AGENTS.override.md` if present, otherwise `~/.codex/AGENTS.md`.
|
|
2. Project scope: from the project root toward the current working directory. In each directory, Codex checks `AGENTS.override.md`, then `AGENTS.md`, then configured fallback names.
|
|
3. 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:
|
|
|
|
```powershell
|
|
rg --files -g 'AGENTS.md' -g 'AGENTS.override.md'
|
|
```
|
|
|
|
When the user asks about global defaults too, inspect:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```markdown
|
|
## 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:
|
|
|
|
```markdown
|
|
### 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.
|