Agents Md Improver

AGENTS.md Improver

Audit and improve Codex AGENTS.md guidance files and companion code_map.md navigation maps so future Codex CLI, Codex App, and native subagent sessions receive concise, accurate, scoped project instructions and fast code search entry points.

Default mode is report-first. Output a quality report and proposed diff before writing. If the user explicitly asks to implement an approved plan, continue directly to targeted edits and verification.

Core Semantics

• An AGENTS.md file governs the directory that contains it and every descendant directory.
• A deeper AGENTS.md adds or overrides guidance for its subtree.
• System, developer, and direct user instructions outrank any AGENTS.md content.
• Repository AGENTS.md files are project guidance. User-level ~/.codex/AGENTS.md is global preference guidance and should not be edited unless explicitly requested.
• AGENTS.md carries durable behavioral constraints, commands, and safety rules. code_map.md carries navigational structure, search anchors, entry points, and generated/ignored directory notes.
• Every created or updated AGENTS.md should explicitly name the relative code_map.md path agents must read before broad grep or repo-wide search, for example See ./code_map.md before broad grep or For this subtree, start with platforms/codex/code_map.md.
• Preserve hook-managed marker blocks such as ... and ... .

Workflow

Phase 1: Discovery

Find scoped guidance files:

# POSIX shells
find . \( -name AGENTS.md -o -name code_map.md \) \
  -not -path './.git/*' \
  -not -path './node_modules/*' \
  -not -path './target/*' \
  -not -path './dist/*' \
  -not -path './build/*' \
  -not -path './.omx/state/*'

# PowerShell
Get-ChildItem -Recurse -Force -Include AGENTS.md,code_map.md |
  Where-Object { $_.FullName -notmatch '\\.git|node_modules|target|dist|build|\\.omx\\state' } |
  Select-Object -ExpandProperty FullName

Exclude generated, vendored, dependency, cache, and build-output directories from guidance creation scans, including .git/, node_modules/, target/, dist/, build/, .omx/state/, vendor/, generated docs output, coverage output, and language-specific package caches.

Discover candidate directories for new nested AGENTS.md plus local code_map.md before proposing writes. Score only real source subtrees that show one or more of:

• independent manifests or command files such as package.json, Cargo.toml, pyproject.toml, go.mod, Makefile, justfile, or CI/workflow fragments
• independent runtime, entry point, test command, deployable package, or service boundary
• distinct language stack, framework, generated-source policy, or data/credential safety boundary
• high internal complexity where a local map would prevent broad grep or repeated rediscovery
• public API/contract surfaces that are frequently edited or shared by multiple packages

Also note, but do not edit by default:

~/.codex/AGENTS.md
.codex/agents/
.codex/skills/

Classify each file:

| Type | Location | Purpose | |---|---|---| | root guidance | ./AGENTS.md | repo-wide commands, architecture, gates, safety boundaries | | nested scoped guidance | .//AGENTS.md | local commands, ownership, generated files, conventions | | root code map | ./code_map.md | repo navigation, top-level routing, search anchors, ignored/generated paths | | nested code map | .//code_map.md | subtree entry points, internal routing, upstream/downstream boundaries | | user global guidance | ~/.codex/AGENTS.md | user-wide preferences, outside repo scope | | generated/runtime guidance | .omx/.../AGENTS.md or similar | runtime state; usually read-only/no-edit |

Phase 2: Evidence Collection

For every repo guidance file, verify claims against the repository:

• commands in package.json, justfile, Cargo.toml, pyproject.toml, Makefile, CI files
• actual directory structure and entry points
• existing code_map.md files, map pointers in AGENTS.md, and whether map content is navigational rather than behavioral
• test/lint/typecheck/build commands
• generated, vendored, secret, data, or deployment-sensitive paths
• nested guidance overlap or conflicts
• unrepresented key subprojects that score high enough for nested guidance creation
• Codex-specific surfaces: .codex/skills, .codex/agents, AGENTS.md scope rules, sandbox/approval notes
• optional OMX sections only when present in the repo or current user environment

Phase 3: Quality Assessment

Use references/quality-criteria.md for detailed scoring, including the nested AGENTS.md creation scorecard.

Quick checklist:

| Criterion | Weight | Check | |---|---:|---| | scope and override clarity | 20 | file explains what subtree it governs and how it relates to parent guidance | | executable commands and gates | 20 | build/test/lint/typecheck commands are real and scoped | | architecture and ownership | 15 | enough map to route future edits without restating obvious code | | safety and permissions | 15 | sandbox, approvals, secrets, destructive operations, external services are clear | | Codex workflow fit | 15 | skills/subagents/plugins/OMX guidance is accurate and not overpromised | | conciseness and currency | 15 | current, dense, non-duplicative, no stale file paths |

For each candidate nested subtree, record:

• creation score and decision: create (>=60), candidate only (40-59), or do not create (`` — passed/failed/skipped with reason

Remaining risks

• ...

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bahayonghang](https://github.com/bahayonghang)
- **Source:** [bahayonghang/my-ai-cli-toolkit](https://github.com/bahayonghang/my-ai-cli-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.