OpenAI Codex — Official Skill-Authoring Guidance

Extracted from OpenAI's first-hand Codex documentation (skills, configuration, custom prompts, and the AGENTS.md guide). Every rule links to its source. Last gathered 2026-07-13.

Codex consumes the Agent Skills base spec plus the skill body. It does not read Claude-only frontmatter extensions. Where Codex diverges from Anthropic, the difference is called out. For the shared field reference see frontmatter-field-spec.md.

Frontmatter

Required frontmatter fields: name and description. Optional skill-level metadata and tool dependencies go in agents/openai.yaml, not inline in SKILL.md.
- Why: Separation of concerns: SKILL.md carries instructions; openai.yaml carries UI presentation and tool dependencies.
- Source: Codex Skills
The description field should explain exactly when the skill should AND should not trigger, not just what it does.
- Why: Explicit negative scoping prevents false positives where a related-but-different task fires the skill.
- Source: Codex skills.md

Naming

If two Codex skills share the same name, Codex does not merge them; both can appear in skill selectors. Name collisions across discovery tiers must be managed explicitly.
- Why: Unlike Claude Code (which has explicit override precedence), Codex exposes both conflicting skills.
- Source: Codex skills.md

Writing the description

The description is the most important part of a Codex skill. It must state what the skill does and when to use it. Include trigger phrases a user would actually say. Scope to one job with 2-3 concrete use cases. Define clear inputs and outputs.
- Why: Implicit matching depends entirely on the description field. Weak descriptions cause missed triggers.
- Source: Codex best-practices
Front-load the key use case and trigger words so Codex can still match the skill if descriptions are shortened when the skills list is large.
- Why: The initial skills list is capped at ~2% of context window or 8,000 chars. Descriptions shorten first when many skills are installed.
- Source: Codex skills.md
AGENTS.md instructions should be concrete and actionable — specify exact commands to run, not vague principles.
- Why: Vague AGENTS.md rules are interpreted inconsistently across sessions.
- Source: openai/codex docs

Skill structure & file layout

Codex skill directory layout: SKILL.md (required), scripts/ (optional), references/ (optional), assets/ (optional), agents/openai.yaml (optional). Do not include scripts or assets unless they measurably improve reliability.
- Why: Unnecessary supporting files add maintenance burden without improving skill behavior.
- Source: Codex best-practices
Skills are discovered from: .agents/skills in CWD or parent dirs up to repo root (repo-scoped), $HOME/.agents/skills (user-level), /etc/codex/skills (admin), and system-bundled. Codex follows symlinked skill folders.
- Why: Understanding discovery order is required to place skills in the right scope and debug missing skills.
- Source: Codex skills.md
Global preferences that apply across all repos go in ~/.codex/AGENTS.md. Repo-level norms go in the project root AGENTS.md. Subdirectory overrides (AGENTS.override.md) apply to that subtree only.
- Why: Layered scope inheritance lets team-wide conventions coexist with package-specific rules.
- Source: Codex AGENTS.md guide
AGENTS.md files are concatenated root-to-cwd with blank lines between them. Files closer to the current directory take effective precedence because they appear later in the combined prompt. The combined size limit is 32 KiB (configurable via project_doc_max_bytes).
- Why: Closer files override earlier guidance by appearing later in the merged prompt seen by the model.
- Source: openai/codex docs
Within each directory, Codex checks for AGENTS.override.md first, then AGENTS.md, then fallback filenames registered in project_doc_fallback_filenames. At most one file per directory is included.
- Why: The override file provides a mechanism for temporary high-priority rules without deleting the base file.
- Source: openai/codex docs
Write imperative steps with explicit inputs and outputs in the SKILL.md body.
- Why: Codex agents follow procedural instructions more reliably than open-ended capability descriptions.
- Source: Codex skills.md
Use skills for reusable processes. Keep AGENTS.md focused on durable project rules only. Do not bloat AGENTS.md with repeatable workflow content.
- Why: AGENTS.md is static project context; skills are invocable, composable workflows. Mixing them degrades both.
- Source: Codex customization
When Codex makes repeated mistakes, codify corrections in AGENTS.md so future sessions inherit the fix.
- Why: AGENTS.md persists across sessions; skills are invoked per-task. Persistent corrections belong in AGENTS.md.
- Source: Codex customization

Supported project surfaces

Use AGENTS.md for project instructions. Codex reads global guidance from ~/.codex/AGENTS.md, then resolves AGENTS.override.md, AGENTS.md, or an explicitly configured fallback from the repository root to the working directory.
- Source: Codex AGENTS.md guide
Use configuration files for runtime behavior. User defaults belong in ~/.codex/config.toml; trusted repositories may add .codex/config.toml overrides. Model, approval, sandbox, provider, and MCP settings are configuration, not reusable prompt content.
- Source: Codex config basics
Use .agents/skills for repository workflows. Codex scans skill directories from the current working directory to the repository root and also supports user/admin skill locations.
- Source: Codex skills
Do not invent .codex/instructions.md or .codex/commands. Neither is a documented repository-local prompt or command surface.
Treat custom prompts as legacy user configuration. They live under ~/.codex/prompts, require explicit invocation, are not shared through a repository, and are deprecated in favor of skills.
- Source: Codex custom prompts

Progressive disclosure

Codex loads skills in three phases: (1) name+description+file path at discovery; (2) full SKILL.md body when selected; (3) scripts/references/assets only during execution. The initial skills list is capped at ~2% of the model's context window, or 8,000 characters when the context window is unknown.
- Why: The budget applies only to the listing phase. When a skill is selected, the full SKILL.md is read regardless of the budget.
- Source: Codex skills.md
If many Codex skills are installed, descriptions are shortened first to fit the budget. For very large skill sets, some skills may be omitted entirely with a warning.
- Why: Description front-loading and conciseness are the defense against omission from the listing.
- Source: Codex skills.md

Invocation & triggering

Two Codex invocation modes: explicit (user names the skill via /skills or $skill) and implicit (Codex auto-selects when task description matches). Set allow_implicit_invocation: false in agents/openai.yaml to require explicit invocation.
- Why: Side-effectful skills should require explicit invocation to prevent unintended automatic triggering.
- Source: Codex skills.md
Test prompts against the skill description to confirm correct trigger behavior before deploying.
- Why: Description matching is the sole implicit-invocation mechanism. Unverified descriptions cause silent mis-triggering.
- Source: Codex skills.md

Tool permissions (allowed-tools / disallowed-tools)

Declare tool dependencies (MCP servers) in agents/openai.yaml under dependencies.tools with type, value, description, transport, and url.
- Why: Declared dependencies enable smoother tool availability when the skill is invoked, without assuming the tool is pre-configured globally.
- Source: Codex skills.md

References & scripts

Prefer instructions over scripts as the Codex default. Use scripts only when you need deterministic behavior or external tooling.
- Why: Instructions are more maintainable and readable. Scripts add complexity that is only justified for deterministic operations.
- Source: Codex skills.md
Register custom fallback filenames (e.g., TEAM_GUIDE.md, .agents.md) in project_doc_fallback_filenames in config.toml so existing team docs are recognized as instruction files without renaming.
- Why: Teams with existing documentation should not need to rename it to get Codex to use it.
- Source: Codex AGENTS.md guide

Testing & evaluation

Do not try to cover every edge case upfront. Start with one representative task, get it working well, then turn that workflow into a skill. A good rule of thumb: if you keep reusing the same prompt or correcting the same workflow, it should become a skill.
- Why: Premature comprehensiveness creates skills that are too broad before the core use case is validated.
- Source: Codex best-practices
Verify AGENTS.md instruction loading by asking Codex to summarize current instructions (codex --ask-for-approval never "Summarize current instructions."). Use --cd subdir to confirm nested overrides function correctly.
- Why: Instruction loading issues (empty files, unexpected overrides, size cap truncation) are silent without explicit verification.
- Source: Codex AGENTS.md guide
Codex detects skill changes automatically. If an update does not appear, restart Codex. AGENTS.md instruction chains rebuild on every run — there is no cache to clear.
- Why: Understanding live-reload vs restart requirements prevents confusion during development iteration.
- Source: Codex skills.md

Anti-patterns

Do not create empty AGENTS.md files — Codex silently ignores them.
- Why: Empty files appear in the filesystem but contribute nothing to the instruction chain.
- Source: openai/codex docs
Do not place unexpected .override.md files in directories — they silently block discovery of the regular AGENTS.md. Check for unexpected override files if instructions are not loading as expected.
- Why: Override files take priority. An unexpected override prevents the intended base file from loading.
- Source: Codex AGENTS.md guide
Do not ignore truncation at the 32 KiB AGENTS.md size cap. Either raise project_doc_max_bytes or split large files across nested directories.
- Why: Truncated instructions cause silent partial loading of guidance — the model proceeds as if the missing content does not exist.
- Source: openai/codex docs
Do not include scripts or asset files in a Codex skill unless they measurably improve reliability.
- Why: Supporting files add complexity. The benefit must outweigh the maintenance cost.
- Source: Codex best-practices
Do not attempt comprehensive edge-case coverage before validating the core workflow. Do not graduate to automation before the skill is reliable in manual use.
- Why: Premature automation of an unreliable workflow amplifies failures.
- Source: Codex best-practices

13 KiB Raw Permalink Blame History