Codex Prompt Templates and AGENTS.md Examples

TL;DR: Codex reads AGENTS.md files root-down, concatenated, with a Codex-only escape hatch, AGENTS.override.md, that most guides skip entirely. Below are working files: a root AGENTS.md, a service-level override, a config.toml snippet for custom filenames, and a reusable SKILL.md template, plus the actual prompt structure OpenAI documents for getting good results out of Codex CLI.

Most AGENTS.md write-ups stop at telling you to add a markdown file to your repo root. That's true, and it's also not the part that trips people up once you're actually running Codex day to day. What trips people up is the override file nobody mentions, the byte cap that silently truncates a file that's grown too long, and the gap between writing instructions and writing a prompt Codex actually acts on well. This post is the working files and the prompt patterns, not another explainer of what AGENTS.md is in the abstract.

Where does Codex actually look for instructions, and in what order?

Codex's own configuration docs describe this as building an instruction chain when it starts, once per run; in the TUI this usually means once per launched session. That chain has two layers, checked in a fixed order.

The global layer lives in your Codex home directory, defaulting to ~/.codex unless you've set CODEX_HOME. OpenAI's own configuration docs put it plainly: "Codex reads AGENTS.override.md if it exists. Otherwise, Codex reads AGENTS.md." It uses only the first non-empty file at this level, never both.

The project layer starts at your repository root and walks down to your current working directory, checking the same two filenames in every directory it passes through. The documented merge rule: "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt." That last part is a real, practical consequence: a rule in a deeply nested directory only fires if you actually launched or cd'd there. A rule sitting in a directory Codex never walks through this run simply never loads.

What does AGENTS.override.md actually do, and why does it matter?

It's a Codex-specific mechanism that most general AGENTS.md write-ups never mention, because it's not part of the open format itself, it's something Codex layers on top. In any directory Codex checks, an AGENTS.override.md takes priority over a regular AGENTS.md sitting right next to it; the regular file is skipped entirely at that level, not merged with the override.

That's the right tool for a temporary exception you don't want to delete the base file to create: a payments team running stricter rules for one sprint, a directory under active migration where the usual conventions are temporarily wrong. Remove the override file and the base guidance is back, untouched.

Which of these three actually fits a given piece of guidance?

What does a working root AGENTS.md look like for a Codex-tracked repo?

Here's a complete file, sized to stay well under the byte cap covered below.

# AGENTS.md

## Setup commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Full check before opening a PR: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- Data fetching lives in `src/server/`. Never fetch from a client component.
- Validation goes through `zod`. Do not add a second validation library.

## Boundaries
- Never edit `src/generated/` — it is rebuilt by `pnpm codegen`.
- `main` auto-deploys on merge. Ask before merging anything to it.

## Code Review Rules

### Database access
- Do not approve a change that adds a raw SQL query without a parameterized
  placeholder for any user-supplied value. Safe path: use the query builder,
  or a parameterized statement if raw SQL is genuinely required.

## Pull requests
- Title format: `[area] what changed`
- Run `pnpm lint` before committing; do not rely on CI to catch formatting.

The ## Code Review Rules section is worth calling out specifically, because it's a documented Codex convention rather than a general AGENTS.md pattern: Codex's own docs describe adding that exact heading to the AGENTS.md closest to the code it governs, so a rule can live at the root for repo-wide checks or in a nested file for one service's specific risks, and Codex's automated code review picks it up from there.

How would a service-level override actually look in practice?

Say the payments service needs a stricter rule than the rest of the repo, temporarily, without touching the root file at all:

# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `pnpm test` for anything under this directory.
- Never rotate API keys without notifying the security channel first.
- This override expires when the PCI audit closes; remove this file then.

Starting Codex from inside services/payments/ loads the global file first, the repository root AGENTS.md second, and this override last, replacing whatever a plain services/payments/AGENTS.md would otherwise have said in that same spot. Delete the override when the audit closes, and the directory falls back to whatever the root file already covers, no cleanup required beyond removing one file.

How do you make Codex recognize a differently-named instructions file?

Some teams already have a TEAM_GUIDE.md or similar predating AGENTS.md entirely, and don't want to duplicate it. Codex supports this through config.toml:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

With that in place, Codex checks each directory in this order: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. A filename that isn't on this list is invisible to instruction discovery no matter how central it is to your team's workflow. The size line matters on its own. OpenAI's docs state it as a hard rule: "Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)." Raising it to 65536, as above, doubles the ceiling; splitting a long file across nested directories is usually the better fix, since a bigger cap still means more of the model's context spent on instructions instead of your actual task.

Context window economics apply here the same way they do to any instruction file: everything loaded competes with the task itself for attention, so the byte cap is a ceiling worth staying well under, not a target to write toward.

How do you confirm what Codex actually loaded, without guessing?

Don't wait for a real task to reveal that the wrong file loaded. Codex's own docs recommend checking directly, before you rely on any of it:

codex --ask-for-approval never "Summarize the current instructions."

That runs with no side effects and no risk of an approval prompt interrupting it, and Codex answers by quoting back whatever it actually loaded, in precedence order, global file first, then root, then any nested override. If the answer doesn't match what you expected, the usual causes are specific and checkable rather than mysterious: an AGENTS.override.md sitting somewhere higher in the tree than you remembered, a fallback filename typo'd in project_doc_fallback_filenames, or simply not being in the directory you think you're in — codex status reports the workspace root Codex is actually using, which is worth confirming before you go looking for a bug that isn't one. Codex rebuilds this chain fresh on every run, so a stale answer isn't a caching problem; it means something upstream in the chain genuinely changed since you last checked.

What's the actual prompt structure that gets good results from Codex?

OpenAI's own prompting documentation gives a specific structure rather than a vague call to just describe what you want: name the goal, the context that changes the result, the output shape you need, and the boundaries that must hold regardless of what Codex decides to do. None of the four are mandatory in every prompt, but skipping boundaries on anything irreversible is where most bad outcomes start.

Here's that structure applied to an actual bug-fix prompt, written the way you'd type it into Codex CLI:

Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but
doesn't persist the change.

Repro:
1) Start the app: npm run dev
2) Go to /settings
3) Toggle "Enable alerts"
4) Click Save
5) Refresh the page — the toggle resets

Constraints:
- Do not change the API shape.
- Keep the fix minimal and add a regression test if feasible.

Start by reproducing the bug locally, then propose a patch and run checks.

The repro steps and constraints are doing more work here than the one-line bug description. Codex can discover the call sites and stack traces on its own by running the reproduction; it can't discover which parts of the current behavior are load-bearing and which are the actual bug, and that's exactly what the constraints line tells it.

What are Codex's own built-in prompt patterns, beyond a plain message?

Three commands worth knowing before you write another prompt from scratch. /plan switches the active chat into plan mode, asking Codex to propose an approach before it touches anything; it's unavailable once Codex is already working on something, so reach for it before you describe the task, not after. /goal <objective> sets a persistent target, up to 4,000 characters, that Codex keeps tracking across turns until you clear it; for anything longer, point the goal at a file instead of pasting the whole thing inline. /review asks Codex to review your current working tree, focusing on behavior changes and missing tests, and takes an optional focus argument the same way: /review Focus on edge cases and security issues.

One more pattern worth building into a habit: when Codex is already mid-task, pressing Enter sends a message that steers the current run, while pressing Tab queues it for the next turn instead. Steer for a correction that changes what's happening right now; queue for a follow-up that should wait until the current work actually finishes, rather than colliding with it mid-edit.

How do you turn a prompt you keep reusing into an actual Codex skill?

A skill is the mechanism for exactly this: instructions you don't want to retype, packaged so Codex loads them on demand instead of every session. OpenAI's own docs define it precisely: "A skill is a directory with a SKILL.md file plus optional scripts and references. The SKILL.md file must include name and description." Codex doesn't load the whole thing up front, either — only each skill's name and description are loaded initially, and OpenAI's docs cap that at "at most 2% of the model's context window, or 8,000 characters when the context window is unknown". The full instructions are read only once Codex actually selects that skill. Here's a minimal one for a recurring task, a pre-PR check that's specific enough to be worth automating but too situational to belong in AGENTS.md itself:

---
name: pre-pr-check
description: Run before opening a pull request. Use when the user says
  "get this ready for a PR" or "run the pre-PR check", not for a general
  code review request.
---

1. Run `pnpm lint && pnpm typecheck && pnpm test`. Report failures verbatim,
   don't summarize them away.
2. Diff against `main` and flag any file over 400 lines changed — ask
   whether it should be split into a smaller PR.
3. Check for a matching test file for every changed file under `src/server/`.
   List any that are missing; don't add tests without asking first.
4. Draft a PR title in the format `[area] what changed` and a two-sentence
   summary. Don't open the PR — just produce the draft.

Save that at .agents/skills/pre-pr-check/SKILL.md in your repository root and commit it. OpenAI's docs describe the discovery rule directly: "Codex scans .agents/skills in every directory from your current working directory up to the repository root." That makes a root-level skill like this one available to anyone working anywhere in the repo, not just from the directory you happened to save it in. Invoke it explicitly with $pre-pr-check, or let Codex match it implicitly when a prompt lines up with the description, which is exactly why the description names the trigger phrases directly instead of just summarizing what the skill does.

A skill saved under $HOME/.agents/skills instead stays personal to you rather than shipping with the repo, which is the right call for something specific to your own workflow rather than a convention your whole team should follow.

How do you run one of these prompts without a human watching?

For CI or a scripted batch, codex exec runs the same agent non-interactively, finishing without waiting on approval from anyone. A minimal CI-style invocation, writing structured output you can actually parse:

codex exec --json "Run the pre-PR check skill and report any failures" > result.jsonl

Codex writes formatted output by default; adding --json switches that to newline-delimited JSON events, one per state change, which is the form worth reaching for the moment a script, not a person, is the thing reading the result. A resume subcommand continues a non-interactive run started earlier in the same working directory, with --last for the most recent session or --all to search across every session on the machine.

Does any of this carry over to other tools, or is it Codex-only?

The filename itself does, broadly. AGENTS.md's own site describes itself as compatible with a growing list of coding agents beyond Codex, and states the format is now stewarded by the Agentic AI Foundation under the Linux Foundation, alongside projects like MCP itself. The oft-repeated "60k open-source projects" adoption figure comes from that same site, not from an independently audited count, so treat it as the format's own claim rather than a verified number.

The mechanics in this post mostly don't transfer, though. AGENTS.override.md, project_doc_fallback_filenames, the ## Code Review Rules convention, and Codex's specific skills mechanism are Codex behavior, not part of the open format itself. Even the everyday case has real exceptions: Claude Code reads CLAUDE.md, not AGENTS.md, by default, and its /init command only reads Cursor and GitHub Copilot rule files unless you set CLAUDE_CODE_NEW_INIT=1, at which point it additionally picks up AGENTS.md itself, plus .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules. Whether your own AGENTS.md file is even being read the way you expect is worth checking per tool; the AGENTS.md standard explained covers that comparison directly, and CLAUDE.md templates for Claude Code is the equivalent starting point on that side.

If Codex is one of several MCP servers or tools you're wiring credentials into alongside all of this, MCP authentication: OAuth vs personal access tokens covers the auth half of that setup, including Codex's own config.toml bearer-token pattern (a bearer_token_env_var key pointing at an environment variable, not a raw secret in the file) for headless runs of the kind codex exec is built for.

Where should you actually start?

Write the root AGENTS.md first, commands and boundaries only, and keep it far under the 32 KiB default. Add an override file only where you have a genuine, temporary exception, not as a default habit. Once you notice yourself retyping the same multi-step prompt for the third time, that's the signal to turn it into a skill instead of a saved snippet somewhere else. And when a task needs to run without you present, whether that's CI or a batch you kick off before leaving for the day, codex exec --json is the form built for a script to read, not a form you should be reading over someone's shoulder in a terminal.