Codex Docs

references/

references/INDEX.md

references/docs_manifest.json

Scope

codex.toml

Workflow

1. If the user supplied a topic, normalize it to a slug:
   • lowercase, strip leading

     /codex/

     , strip surrounding slashes
   • join nested segments with

     __

     (e.g.

     cli features

     ->

     cli__features

     ,

     guides agents-md

     ->

     guides__agents-md

     )
2. 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.
3. If no exact match, read

   references/INDEX.md

   and pick the closest topic. If still ambiguous, list the candidates and ask.
4. 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

1. Suggest the user run

   npx skills update codex-docs

   .
2. Cross-check the canonical URL via

   original_url

   in

   references/docs_manifest.json

   and offer it as a follow-up source.
3. If a specific page failed MDX cleaning, the unmodified source is preserved at

   references/_raw/<slug>.md

   -- read that as a fallback.

Examples

references/hooks.md

references/cli__features.md

references/cloud__environments.md

references/guides__agents-md.md

references/INDEX.md