AGENTS.md Authoring skill for Codex

A good AGENTS.md is short, specific to this repository, and verifiable: every command in it runs as written, every rule is something Codex would get wrong without being told, and nothing in it restates what the code, the README or the linter already enforces.

How Codex reads it (facts to design around)

• Codex builds an instruction chain once per run (once per TUI session): the global file in CODEX_HOME (~/.codex/AGENTS.override.md, else ~/.codex/AGENTS.md), then one file per directory from the project root down to the working directory.
• In each directory it takes the first non-empty file among AGENTS.override.md, AGENTS.md, then any names in project_doc_fallback_filenames. Empty files are skipped.
• Files are concatenated root first, so deeper files appear later and win on conflicts.
• Loading stops once the combined text reaches project_doc_max_bytes (default 32 KiB). Anything past the cap is silently dropped, so the most important rules go first.
• The project root is the nearest directory containing .git unless project_root_markers says otherwise.
• AGENTS.md is also read by Codex code review on GitHub: a ## Code Review Rules section in the file nearest the changed code steers what the reviewer flags.

For nested files in monorepos, per-package overrides and precedence debugging, use the agents-md-monorepo skill instead; this skill covers writing one good file.

Workflow

- [ ] 1. Inventory what the repo already declares
- [ ] 2. Run every candidate command and record the real ones
- [ ] 3. Collect the non-obvious conventions and boundaries
- [ ] 4. Draft using the template below
- [ ] 5. Cut: remove anything Codex would do right anyway
- [ ] 6. Verify the file loads and the commands work

1. Inventory before writing

Read, do not guess:

ls -a; git ls-files | head -100
cat package.json 2>/dev/null | head -60          # scripts, packageManager, engines
ls *.lock pnpm-lock.yaml yarn.lock package-lock.json bun.lockb uv.lock poetry.lock Cargo.lock go.sum 2>/dev/null
cat Makefile justfile Taskfile.yml 2>/dev/null | head -80
ls .github/workflows/ 2>/dev/null && sed -n 1,120p .github/workflows/*.yml
cat .editorconfig .nvmrc .tool-versions .python-version 2>/dev/null
find . -name AGENTS.md -o -name AGENTS.override.md | grep -v node_modules

CI workflows are the most reliable source of the real commands: they are what must pass. If an AGENTS.md already exists, read it fully and mark each line keep, fix or cut.

2. Prove the commands

Run each command you intend to document, in the sandbox Codex will use. Record:

• The fastest way to run one test file or one test case (Codex uses this constantly).
• The full check that CI runs before merge.
• Whether a command needs network, a running service, or secrets. If it does, say so in the file, because Codex sessions often run with network off.

Never document a command you did not see succeed. If one fails, fix the repo or write the working variant, not the aspirational one.

3. Collect what is not obvious

Good material for AGENTS.md:

Include	Example
Package manager and version constraints	“Use pnpm 9; never run npm install, it rewrites the lockfile”
Narrow test commands	“pnpm vitest run path/to/file.test.ts -t 'name'”
Generated files and their generators	“src/gen/ is generated by make proto; edit .proto files instead”
Architectural boundaries	“Handlers never import from db/; go through services/”
Repo-specific traps	“Tests share one Postgres DB; run them with --runInBand”
Hard boundaries	“Never edit migrations/ that are already merged; add a new migration”
Definition of done	“Done means make check passes and new behavior has a test”

Leave out: general coding advice (“write clean code”), style rules a formatter enforces, long architecture essays (link to docs instead), secrets or internal URLs that should not live in the repo, and anything that changes weekly.

4. Draft with this skeleton

# AGENTS.md

## Commands
- Install: `pnpm install --frozen-lockfile`
- Typecheck: `pnpm tsc --noEmit`
- Lint: `pnpm lint` (autofix: `pnpm lint --fix`)
- Test one file: `pnpm vitest run src/foo/foo.test.ts`
- Full check before finishing: `pnpm check` (runs typecheck, lint, tests; same as CI)
- Needs network: `pnpm e2e` (Playwright, downloads browsers) — skip when offline and say so

## Project map
- `apps/web` Next.js frontend; `packages/api` tRPC server; `packages/db` Drizzle schema
- Generated: `packages/db/drizzle/` (run `pnpm db:generate`, never hand-edit)

## Conventions
- Validate all external input with zod at the router boundary.
- Money is integer cents (`number`), never floats.
- New UI components go in `apps/web/components/<area>/`, colocated test file.

## Boundaries
- Do not add production dependencies without asking.
- Do not modify `.github/workflows/` or `infra/` unless the task says so.
- Never commit, push or open PRs unless asked.

## Done means
- `pnpm check` passes locally.
- Changed behavior has a test that fails without the change.
- Summary lists commands run and their results.

Keep headings stable and imperative. Use exact paths and commands in backticks. Target 40 to 150 lines for a single-package repo. Past roughly 200 lines, split by directory (see agents-md-monorepo) or move rarely needed detail into docs/ and link it.

5. Cut ruthlessly

For every line ask: would Codex do the wrong thing without it? If not, delete it. Specific failure modes to remove:

• Contradictions with tooling (AGENTS.md says Prettier, repo uses Biome).
• Duplicates of the README setup section. Link instead.
• Vague imperatives (“be careful with the database”). Replace with the concrete rule.
• Instructions for humans (PR etiquette for reviewers, meeting notes).

6. Verify

1. Confirm Codex sees the file without spending a model turn:

   codex debug prompt-input > /tmp/prompt-input.json
   grep -c "Full check before finishing" /tmp/prompt-input.json   # expect >= 1

   Pick a distinctive phrase from your file. If it is missing, check for an AGENTS.override.md higher up or in ~/.codex/, and check file size.
2. Ask Codex to restate the rules, non-interactively:

   codex exec --ephemeral "List the commands and boundaries from your project instructions. Quote them."

3. Check size: wc -c AGENTS.md (plus every file in the chain) stays well under 32768 bytes, or project_doc_max_bytes if raised in ~/.codex/config.toml.
4. Run each documented command one final time.

If Codex still uses the wrong command in practice, the rule is either too far down, phrased as a suggestion, or contradicted by a script name. Move it to ## Commands, make it an imperative, and name the wrong alternative explicitly.

Gotchas

• /init writes a scaffold from a quick scan. Treat it as a draft: it often invents plausible commands. Run each one before keeping it.
• An empty or whitespace-only AGENTS.md is skipped, so a deeper or fallback file can take over unexpectedly.
• ~/.codex/AGENTS.override.md silently replaces the global AGENTS.md. Leftover overrides are the most common cause of “Codex ignores my instructions”.
• Changes apply on the next run or new TUI session, not mid-session.
• In CI and the GitHub Action, AGENTS.md from a pull request branch is untrusted input: a contributor can edit it to steer the agent. Review AGENTS.md diffs like code.
• Do not put tokens, hostnames of private systems or customer data in AGENTS.md.
• Phrases like “always” and “never” are followed literally. Use them only for real boundaries, and give the safe alternative next to the prohibition.

Output contract

When finishing, report:

**AGENTS.md:** created | updated (N lines, N bytes)
**Commands verified:** `pnpm check` (pass), `pnpm vitest run <file>` (pass), `pnpm e2e` (needs network, not run)
**Removed:** 12 lines duplicating README setup; outdated `yarn` instructions
**Open questions:** whether `infra/` edits are ever allowed