codex-docs

Codex Docs

Local mirror of OpenAI Codex documentation, kept fresh by a 3-hour GitHub Action. The cleaned Markdown lives in references/; the auto-generated topic list lives in references/INDEX.md; the per-file manifest with upstream URLs lives in references/docs_manifest.json.

Scope

Use this skill for Codex-specific product and configuration questions, including CLI behavior, codex.toml, slash commands, Codex hooks, skills, MCP, subagents, AGENTS.md, prompts, sandboxing, cloud environments, models, pricing, security, migrations, and use-case recipes. If the question is about Claude Code hooks, Cursor, general OpenAI APIs, ChatGPT, GPT models, or another non-Codex product, this skill does not apply.

Workflow

If the user supplied a topic, normalize it to a slug:
- lowercase, strip leading /docs/ or /codex/, strip surrounding slashes
- join nested segments with __ (e.g. cli features -> cli__features, agent-configuration agents-md -> agent-configuration__agents-md)
If references/<slug>.md exists, read that file directly. Do NOT grep the whole references/ tree first - the index plus targeted reads is faster and uses less context.
If no exact match, read references/INDEX.md and pick the closest topic. If still ambiguous, list the candidates and ask.
If the user supplied no topic, read references/INDEX.md and present the available topics.

Answer format

Lead with a direct answer to the user's question grounded in the file you read.
Quote short snippets (commands, config keys) when they appear verbatim in the doc.
End with Source: <upstream URL> using the original_url from the file frontmatter or references/docs_manifest.json.

Freshness and fallback

The mirror is refreshed every 3 hours by upstream CI, which fails rather than committing frozen content. If the local content looks stale, contradicted by the user, or empty:

Suggest the user run npx skills update codex-docs.
Check the file's entry in references/docs_manifest.json: a status of stale means upstream could not be reached on the last run.
Cross-check the canonical URL via original_url in references/docs_manifest.json and offer it as a follow-up source.
If a specific page failed MDX cleaning, the unmodified source is preserved at references/_raw/<slug>.md -- read that as a fallback.

Examples

User asks	Read
"How do Codex hooks work?"	`references/hooks.md`
"What CLI flags and slash commands exist?"	`references/developer-commands.md`
"What can I set in config.toml?"	`references/config-file__config-reference.md`
"How do cloud environments work?"	`references/environments__cloud-environment.md`
"How should I write AGENTS.md?"	`references/agent-configuration__agents-md.md`
No topic or unclear topic	`references/INDEX.md`