| name | Codex Framework |
| description | Reference knowledge for OpenAI Codex CLI compatibility — how Codex discovers AGENTS.md instructions and .agents/skills so a Forge (Claude Code) project can interoperate with Codex without duplicating agent definitions. Use when a user asks to "add Codex support", make the repo "work with Codex CLI" / "work with both Claude Code and Codex", share governance state between the two tools, or when comparing AGENTS.md vs CLAUDE.md discovery. REFERENCE ONLY — never auto-creates AGENTS.md or .agents/ files.
|
| when_to_use | add codex support, codex cli, AGENTS.md, .agents/skills, dual-tool repo, claude code and codex, interoperate with openai codex, share governance.json between tools, AGENTS.md vs CLAUDE.md
|
| allowed-tools | Read, Grep, Glob |
| disable-model-invocation | true |
Codex CLI — Reference Knowledge
REFERENCE ONLY. Do NOT create AGENTS.md, AGENTS.override.md, SKILLS.md, or .agents/
on your own initiative. NXTG-Forge delivers agents and skills through the Claude Code plugin
system, not Codex-style files. Only scaffold Codex files when the user explicitly asks to add
Codex support (see the worked example below).
How Codex CLI discovers instructions (AGENTS.md)
Codex builds one instruction chain per run by concatenating files from two layers, joined by
blank lines — it does NOT pick a single "winning" file:
- Home layer (
~/.codex, or $CODEX_HOME): reads AGENTS.override.md if present, else
AGENTS.md. First non-empty file at this level only.
- Project layer: from the project root (usually the git root) walking down to the current
working directory, in each directory it takes at most one of:
AGENTS.override.md, then
AGENTS.md, then any name in project_doc_fallback_filenames (config-driven). All matched files
are concatenated root-first.
A nested AGENTS.md in a subdirectory adds to (does not replace) the root one — closer files
come later in the concatenation, so they refine rather than override.
Rough Claude Code analogues (not 1:1 — see Gotchas):
CLAUDE.md ↔ AGENTS.md (repo-wide instruction file).claude/agents/*.md ↔ persona/role blocks written inline in AGENTS.md.claude/skills/*/SKILL.md ↔ .agents/skills/*/SKILL.md
How Codex discovers skills
Codex reads skills from repository, user, admin, and system locations. For a repo, it scans
.agents/skills in every directory from the current working directory up to the repo root.
Each skill is a folder with a SKILL.md:
.agents/skills/
skill-name/
SKILL.md # YAML frontmatter (name, description) + instructions
Codex uses the same progressive-disclosure model as Claude Code: it loads each skill's name,
description, and file path up front, and only reads the full SKILL.md body when it decides to
use that skill. So a good Codex description is a routing rule, exactly as in this plugin.
Forge ↔ Codex interoperability
When a project must support BOTH Claude Code (via Forge) and Codex CLI:
- Forge owns the Claude Code surface — plugin commands, agents, skills, hooks.
- Codex reads its own files —
AGENTS.md, .agents/skills/.
- Shared state — both can read
.claude/governance.json (the governance-mcp state file) for
project context. This is the safe common denominator; no cross-tool code coupling.
- No duplication — do NOT copy Forge's plugin agents into
AGENTS.md. The two runtimes have
different capabilities; a copied agent misleads more than it helps.
Worked example — "add Codex support to my repo"
Input: user says "make this repo work with Codex CLI too."
Action:
- Confirm intent (this is the only path that writes Codex files).
- Read the repo's
CLAUDE.md / .claude/governance.json for existing project context.
- Write a project-specific
AGENTS.md at repo root — role, prime directive, stack assumptions,
output contract, quality gates. Point it at .claude/governance.json for shared state. Do NOT
paste Forge agent definitions into it.
- If the user wants Codex skills, create
.agents/skills/<name>/SKILL.md with name +
description frontmatter. Keep them separate from Forge's skills/ — different runtime.
Output: a Codex-native AGENTS.md (+ optional .agents/skills/) that coexists with, and does not
duplicate, the Forge plugin.
Key differences: Claude Code (Forge) vs Codex CLI
| Aspect | Claude Code (Forge) | Codex CLI |
|---|
| Instruction file | CLAUDE.md (imports, memory) | AGENTS.md (concatenated home + project chain) |
| Agent definitions | Plugin agents/*.md | Inline persona blocks in AGENTS.md |
| Skills | Plugin skills/*/SKILL.md | .agents/skills/*/SKILL.md (scanned up-tree) |
| Skill loading | Progressive (name/desc first) | Progressive (name/desc/path first) |
| Project config | CLAUDE.md + governance.json | AGENTS.md + config.toml |
| Plugin/marketplace | Yes | No (repo/user/admin/system dirs) |
| Multi-agent | Agent Teams (Task tool) | Sequential |
Gotchas
- AGENTS.md concatenates, it does not override. A nested
AGENTS.md refines the root file; both
are included. Don't assume the deepest file "wins" — write nested files as additive refinements.
The only true override is AGENTS.override.md (or config project_doc_fallback_filenames).
AGENT.md (singular) is NOT a Codex default. The Codex override file is AGENTS.override.md;
singular AGENT.md only works if added to project_doc_fallback_filenames. Prior versions of this
skill listed AGENT.md as a first-class location — that was wrong.- The analogy to Claude Code is loose.
AGENTS.md maps to CLAUDE.md in role only. Claude's
.claude/agents/*.md are separately-dispatchable subagents; Codex has no equivalent — its
"agents" are prose personas inside one instruction chain. Don't promise Task-style parallelism.
- Never create Codex files as a side effect. This skill's whole warning exists because the
natural next action after reading it is to scaffold
AGENTS.md. Only do so on an explicit request.
- Codex skill descriptions are routing rules too. Because Codex loads only name/description up
front, a vague description hurts routing in Codex exactly as in Claude Code — carry the same
"what it does + when to use" discipline into any
.agents/skills/*/SKILL.md you author.
Additional resources
