# Bahayonghang My Claude Code Settings Agents Md Improver

> AGENTS.md Improver

- Skill: `tomevault-io/bahayonghang-my-claude-code-settings-agents-md-improver` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/bahayonghang-my-claude-code-settings-agents-md-improver`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/bahayonghang-my-claude-code-settings-agents-md-improver/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/bahayonghang-my-claude-code-settings-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 `<!-- OMX:RUNTIME:START --> ... <!-- OMX:RUNTIME:END -->` and `<!-- OMX:TEAM:WORKER:START --> ... <!-- OMX:TEAM:WORKER:END -->`.

## Workflow

### Phase 1: Discovery

Find scoped guidance files:

```bash
# 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:

```text
~/.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 | `./<subtree>/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 | `./<subtree>/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 (`<40`)
- nearest applicable `code_map.md` path and whether a local nested map should be created
- reason not to create guidance for generated, vendored, dependency, or low-signal directories

Grades:

- **A (90-100)**: scoped, current, executable, and concise
- **B (70-89)**: useful with minor gaps
- **C (50-69)**: basic but missing key operational detail
- **D (30-49)**: sparse, stale, or confusing
- **F (0-29)**: missing, misleading, or unsafe

### Phase 4: Report Before Editing

Always provide this report before edits unless the user already approved an implementation plan.

```markdown
## AGENTS.md Quality Report

### Summary
- Files found: X
- Root guidance: present/missing
- Root code map: present/missing
- Nested scoped files: X
- Nested code maps: X
- Average score: X/100
- Files needing update: X
- Candidate nested guidance dirs: X create / X candidate-only / X skipped

### Scope Map
| File | Governs | Parent guidance | Notes |
|---|---|---|---|
| `AGENTS.md` | repo root | none | ... |
| `packages/api/AGENTS.md` | `packages/api/**` | root | ... |

### Code Map Coverage
| Map | Covers | Referenced by | Notes |
|---|---|---|---|
| `code_map.md` | repo root | `AGENTS.md` | ... |

### Nested Guidance Candidates
| Directory | Score | Decision | Evidence |
|---|---:|---|---|
| `packages/api/` | 75 | create `packages/api/AGENTS.md` + `packages/api/code_map.md` | independent tests, deploy boundary |

### File-by-File Assessment

#### 1. `AGENTS.md`
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|---|---:|---|
| scope and override clarity | X/20 | ... |
| executable commands and gates | X/20 | ... |
| architecture and ownership | X/15 | ... |
| safety and permissions | X/15 | ... |
| Codex workflow fit | X/15 | ... |
| conciseness and currency | X/15 | ... |

**Issues**
- ...

**Proposed changes**
- ...
```

### Phase 5: Targeted Updates

When approved or already authorized by a plan:

1. Preserve existing human-authored guidance unless it is demonstrably stale.
2. Keep root guidance global and short.
3. Keep architecture/search navigation in `code_map.md`; keep behavioral rules, commands, and safety constraints in `AGENTS.md`.
4. Move subtree-specific detail to the narrowest applicable nested `AGENTS.md` instead of duplicating it everywhere.
5. Create nested guidance only when candidate scoring justifies it; list lower-scoring candidates in the report instead of adding noise.
6. Ensure every updated `AGENTS.md` names the exact relative `code_map.md` path agents should read first.
7. Preserve marker blocks exactly unless the user explicitly asks to repair them.
8. Prefer additions or surgical rewrites over wholesale replacement.
9. Remove stale commands only after verifying current replacements.
10. Do not add generic advice that Codex already knows.

### Phase 6: Verification

Run the smallest checks that prove the edits:

- `git diff --check`
- command existence checks for newly documented commands when cheap
- targeted checks that generated `AGENTS.md` files reference an explicit relative `code_map.md` path
- targeted checks that generated or vendored directories were not assigned meaningless nested guidance
- repo docs or lint gates when AGENTS.md is part of a larger docs change
- targeted search for stale names or paths removed by the update

If a documented full gate is expensive, state whether it was run or why it was not.

## Reference Files

- `references/quality-criteria.md` — scoring rubric and red flags
- `references/templates.md` — root, monorepo package, frontend/backend/docs templates
- `references/update-guidelines.md` — what to add, avoid, and preserve

## Common Issues to Flag

- root `AGENTS.md` missing commands required by CI or local development
- root `AGENTS.md` missing an explicit `./code_map.md` pointer when a root map exists or should exist
- nested `AGENTS.md` contradicts parent guidance without saying why
- nested `AGENTS.md` only says "read the code map" without naming the relative map path
- `AGENTS.md` bloated with directory index content that belongs in `code_map.md`
- low-score, generated, vendored, dependency, or build-output directories receiving unnecessary nested guidance
- stale paths after a refactor
- Claude-only guidance copied into Codex files without AGENTS.md scope semantics
- dangerous operations not gated by explicit approval language
- external production services or credentials not called out
- skills/subagents/plugins described as available when they are only aspirational
- OMX workflows documented as universal Codex features instead of environment-specific enhancements

## Final Output After Edits

```markdown
## AGENTS.md Update Summary

### Files changed
- `AGENTS.md` — ...
- `packages/api/AGENTS.md` — ...
- `code_map.md` — ...
- `packages/api/code_map.md` — ...

### What improved
- scope/override clarity
- command/gate accuracy
- safety boundaries
- map-first search flow with explicit relative `code_map.md` paths

### Verification
- `git diff --check` — passed
- `<targeted command>` — passed/failed/skipped with reason

### Remaining risks
- ...
```

---
> Source: [bahayonghang/my-claude-code-settings](https://github.com/bahayonghang/my-claude-code-settings) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->