Skip to content
Skills Library
AI & agents · Learning & explanation

Codex Framework

/Codex Framework

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.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Triggers from the description

add Codex supportwork with Codex CLIwork with both Claude Code and Codex
Original author 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.

How it works

  1. How Codex CLI discovers instructions (AGENTS.md)
  2. How Codex discovers skills
  3. Forge ↔ Codex interoperability
  4. Worked example — "add Codex support to my repo"
  5. Key differences: Claude Code (Forge) vs Codex CLI
  6. Gotchas
  7. Additional resources
Original SKILL.md headings · 106 lines, 831 words
SKILL.md preview
---
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:

1. **Home layer** (`~/.codex`, or `$CODEX_HOME`): reads `AGENTS.override.md` if present, else
   `AGENTS.md`. First non-empty file at this level only.
2. **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:

1. **Forge owns the Claude Code surface** — plugin commands, agents, skills, hooks.
2. **Codex reads its own files** — `AGENTS.md`, `.agents/skills/`.
3. **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.
4. **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:
1. Confirm intent (this is the only path that writes Codex files).
2. Read the repo's `CLAUDE.md` / `.claude/governance.json` for existing project context.
3. 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.
4. 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

- [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Codex customization / discovery precedence](https://developers.openai.com/codex/concepts/customization)
- [Build skills (Codex SKILL.md)](https://developers.openai.com/codex/skills)

Versions

The database has no other skills named Codex Framework.

Database snapshot: 13.11.2026 · package version a0b0f164ad93 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90codex-cli-specialist
    OpenAI Codex CLI and cross-platform skill authoring. Use when setting up Codex CLI, converting or syncing skills between Claude Code and Codex, configuring agents/openai.yaml, or validating cross-platform skill compatibility.
  • 100agents-md-starter
    Creates or upgrades a repository's AGENTS.md (read by Codex, Cursor, and other agents) and a CLAUDE.md that imports it, so Claude Code, Codex, Cursor and Gemini CLI share one set of project rules. Scans the repo to detect languages, package manager, real build/test/lint…
  • 100agents-md-author
    Bootstrap or update project AI-agent instruction files (AGENTS.md for Codex, CLAUDE.md for Claude Code, or both) from the current project's structure. Triggers on: write AGENTS.md, write CLAUDE.md, generate AGENTS.md, agent instructions, project conventions for AI, bootstrap…
  • 90Gemini Framework
    Reference knowledge for Google Gemini CLI compatibility. Describes how Gemini CLI discovers context (GEMINI.md), configures settings.json, and overrides its system prompt so Forge can interoperate on a dual-platform project. Use when a user asks how Forge coexists with Gemini…
  • 95ai-coding-agents
    Comprehensive guide for using Codex CLI (OpenAI) and Claude Code CLI (Anthropic) - AI-powered coding agents. Use when orchestrating CLI commands, automating tasks, configuring agents, or troubleshooting issues.
  • 90Codex Integration
    Use this skill when delegating complex coding tasks to OpenAI Codex CLI and coordinating work between Claude and Codex.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.