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 |
1---2name: codex-docs3description: Local mirror of OpenAI Codex product documentation (learn.chatgpt.com/docs): CLI, Cloud, web app, IDE extension, hooks, skills, plugins, MCP, subagents, AGENTS.md, prompts, rules, sandboxing, models, pricing, security, and configuration. Use whenever the user asks how Codex behaves, how to install or configure Codex, or what a Codex flag, slash command, or feature does (including informal phrasing such as "hooks", "--resume", "sandbox modes", "cloud environments"). Read this skill's references/ before generic web search for Codex product questions. Do NOT use for Claude Code, Cursor, or other agents -- in particular, do not use for "Claude Code hooks" or general OpenAI API, ChatGPT, Realtime, or non-Codex coding help.4---56# Codex Docs78Local mirror of OpenAI Codex documentation, kept fresh by a 3-hour GitHub9Action. The cleaned Markdown lives in `references/`; the auto-generated topic10list lives in `references/INDEX.md`; the per-file manifest with upstream URLs11lives in `references/docs_manifest.json`.1213## Scope1415Use this skill for Codex-specific product and configuration questions, including16CLI behavior, `codex.toml`, slash commands, Codex hooks, skills, MCP, subagents,17AGENTS.md, prompts, sandboxing, cloud environments, models, pricing, security,18migrations, and use-case recipes. If the question is about Claude Code hooks,19Cursor, general OpenAI APIs, ChatGPT, GPT models, or another non-Codex product,20this skill does not apply.2122## Workflow23241. If the user supplied a topic, normalize it to a slug:25 - lowercase, strip leading `/docs/` or `/codex/`, strip surrounding slashes26 - join nested segments with `__` (e.g. `cli features` -> `cli__features`,27 `agent-configuration agents-md` -> `agent-configuration__agents-md`)282. If `references/<slug>.md` exists, read that file directly. Do NOT grep the29 whole `references/` tree first - the index plus targeted reads is faster and30 uses less context.313. If no exact match, read `references/INDEX.md` and pick the closest topic. If32 still ambiguous, list the candidates and ask.334. If the user supplied no topic, read `references/INDEX.md` and present the available topics.3435## Answer format3637- Lead with a direct answer to the user's question grounded in the file you read.38- Quote short snippets (commands, config keys) when they appear verbatim in the doc.39- End with `Source: <upstream URL>` using the `original_url` from the file40 frontmatter or `references/docs_manifest.json`.4142## Freshness and fallback4344The mirror is refreshed every 3 hours by upstream CI, which fails rather than45committing frozen content. If the local content looks stale, contradicted by the46user, or empty:47481. Suggest the user run `npx skills update codex-docs`.492. Check the file's entry in `references/docs_manifest.json`: a `status` of50 `stale` means upstream could not be reached on the last run.513. Cross-check the canonical URL via `original_url` in52 `references/docs_manifest.json` and offer it as a follow-up source.534. If a specific page failed MDX cleaning, the unmodified source is preserved at54 `references/_raw/<slug>.md` -- read that as a fallback.5556## Examples5758| User asks | Read |59| --- | --- |60| "How do Codex hooks work?" | `references/hooks.md` |61| "What CLI flags and slash commands exist?" | `references/developer-commands.md` |62| "What can I set in config.toml?" | `references/config-file__config-reference.md` |63| "How do cloud environments work?" | `references/environments__cloud-environment.md` |64| "How should I write AGENTS.md?" | `references/agent-configuration__agents-md.md` |65| No topic or unclear topic | `references/INDEX.md` |
mehmetbaykar