Codex Skills vs AGENTS.md

Both are markdown files that tell Codex how to work. They load at completely different times, and that's the whole decision.

The rule: if Codex needs it on every task, it's AGENTS.md. If Codex needs it only when a specific job comes up, it's a skill.

The short version

	AGENTS.md	Skill
Loads	Always, before work starts	Only when invoked or description-matched
Costs	Full file, every session	A name and description until used
Size limit	32 KiB combined, all files	Index capped at 2% of context or 8,000 chars
Holds	Facts and standing rules	A procedure, plus optional scripts and references
Invoked	Never — it's just there	`$skill-name`, or automatically on description match
Lives in	`AGENTS.md` at repo root and below	`.agents/skills/<name>/SKILL.md`
Good for	Build commands, conventions, architecture notes	Release notes, threat models, PR triage, deploys

Worth noting: OpenAI documents both systems thoroughly and never compares them. The two docs pages don't reference each other, which is a large part of why this question keeps getting asked.

Why context cost is the deciding factor

AGENTS.md is unconditional. Codex reads the chain of files before it starts and they occupy context whether or not the current task needs them. The combined size is capped at 32 KiB by default (project_doc_max_bytes), and Codex simply stops adding files once it hits that ceiling — so an oversized AGENTS.md doesn't just waste context, it can silently push out other files further down the chain.

Skills are the opposite. Codex loads only each skill's name and description up front, then pulls the full body when it decides to use one. That index has its own cap — 2% of the context window or 8,000 characters, whichever is smaller — but a skill's actual instructions cost nothing until they're needed.

So the practical test isn't "is this important?" It's "does Codex need this on every task, or only on some?" Something needed every time earns its permanent slot. Something needed occasionally should not be taxing every unrelated request.

Where each one lives

The two systems have separate discovery chains, and mixing them up is a common source of "why isn't Codex reading this."

AGENTS.md loads from:

~/.codex/AGENTS.md (or AGENTS.override.md) — global, applies everywhere
Then, from the git root down to your working directory, AGENTS.override.md then AGENTS.md in each directory

Files are concatenated with blank lines between them, and files closer to your working directory win, because they land later in the combined prompt. That's what makes per-package overrides work: a rule in services/payments/AGENTS.override.md beats the repo-wide default when you're working in that directory.

Skills load from .agents/skills/ in every directory between the project root and your working directory, plus ~/.agents/skills for personal ones — and, still, the deprecated ~/.codex/skills. The flagship guide has the full table.

Note the asymmetry in the global slot: AGENTS.md's global location is ~/.codex/AGENTS.md, while the current global skills location is ~/.agents/skills. Same tool, two different home directories, for historical reasons.

Deciding, case by case

You want Codex to…	Put it in
Run `pnpm test` rather than guessing the test command	AGENTS.md
Know the repo is a monorepo with packages under `apps/`	AGENTS.md
Never commit directly to `main`	AGENTS.md
Follow your code review checklist when you ask for a review	Skill
Produce a threat model on request	Skill
Draft release notes from merged PRs	Skill
Use tabs, not spaces	AGENTS.md
Deploy to staging, with a human approving first	Skill (with `allow_implicit_invocation: false`)

The pattern: AGENTS.md holds facts and constraints that are true regardless of the task. Skills hold procedures you invoke for a particular kind of work.

The migration signal

The clearest sign you've outgrown AGENTS.md is a section that has stopped being a fact and become a procedure — numbered steps, a checklist, "first do this, then that." That's a skill wearing the wrong clothes, and it's costing you context on every unrelated request.

Moving it is straightforward: cut the section into .agents/skills/<name>/SKILL.md, write a description naming the situations it applies to, and leave a one-line pointer in AGENTS.md if the existence of the procedure is itself worth knowing. How to create a Codex skill covers writing the description so Codex triggers it at the right moment.

It works the other way too. A skill that turns out to be relevant to every task was never really a skill — if Codex should always follow it, the description-matching layer is just overhead, and it belongs in AGENTS.md.

They're complementary, not competing

The two systems are designed to be used together, and the best setups do. AGENTS.md tells Codex what your project is: how to build it, what the conventions are, what's off-limits. Skills tell Codex how to perform specific jobs within that context. A skill that generates a migration doesn't need to restate your database conventions — AGENTS.md already did, and it's already loaded.

One portability note if you work across agents: AGENTS.md is an increasingly cross-agent convention, and SKILL.md is a formal open standard implemented by Claude Code, Hermes Agent, and others. Both travel reasonably well. Codex-specific pieces — AGENTS.override.md, the agents/openai.yaml metadata block — do not.

Caveats

We have not run Codex. Everything here is documented behavior or verified in the openai/codex source.
The 32 KiB AGENTS.md cap and the 2%/8,000-character skills index cap are both defaults documented as of August 2026; project_doc_max_bytes is configurable.
The comparison itself is our editorial framing. OpenAI documents both systems but does not compare them, so the decision rules above are our reading of how the two behave, not an official recommendation.

Sources

Codex — AGENTS.md (official docs) — paths, override chain, and the 32 KiB limit
Codex — Build skills (official docs) — progressive disclosure and the skills index budget
openai/codex — codex-rs/ext/skills/src/host_roots.rs — the skill discovery chain