Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/skills/llms.txt

Use this file to discover all available pages before exploring further.

The OpenAI Docs skill gives Codex authoritative, always-current access to the OpenAI developer documentation without leaving your coding session. It powers three distinct workflows: general API and SDK docs lookup (with page-level citations), model selection and migration guidance (fetching the live latest-model page before answering), and Codex self-knowledge synthesis (pulling the current Codex manual and generating a navigable outline). When the live MCP server is reachable, Codex reads the actual published docs; bundled reference files serve as a fallback when network access is unavailable.
The OpenAI Docs skill is a system skill — it is pre-installed in every Codex environment and cannot be removed by users.

​
What this skill provides

Live docs via MCP

Searches and fetches pages from developers.openai.com using the openaiDeveloperDocs MCP server — search, fetch, and OpenAPI spec tools included.

Latest model guidance

Fetches https://developers.openai.com/api/docs/guides/latest-model.md to give up-to-date model IDs, use-case recommendations, and migration links.

Codex self-knowledge

Fetches and caches the full Codex manual, generates a section outline, and answers questions about skills, plugins, MCP, hooks, automations, and surface selection.

Prompt upgrade guidance

Provides prompt-rewrite guidance for newer models, covering outcome-first prompting, stopping conditions, personality blocks, and formatting.

​
Default prompt

When this skill activates, Codex uses the following operating instruction:
Use OpenAI Docs for official docs lookup, questions about Codex itself or Codex surfaces, model selection, model migration, and prompt-upgrade work.

​
When it triggers

This skill activates when you:
  • Ask how to build with an OpenAI API or SDK
  • Ask about Codex itself — configuration, surfaces, skills, plugins, MCP, hooks, or automations
  • Need to choose the right model for a use case
  • Want to migrate from an older model string to the current default
  • Need a prompt rewritten for a newer model’s behavior
  • Ask for citations or links to official OpenAI documentation
For questions about building API-backed apps that need credentials, the skill defers to openai-platform-api-key first, then returns here for the docs portion of your question.

​
Resources and when each is loaded

ResourceWhen loaded
mcp__openaiDeveloperDocs__search_openai_docsFirst call for any non-Codex docs question
mcp__openaiDeveloperDocs__fetch_openai_docAfter search, to read the best matching page
mcp__openaiDeveloperDocs__get_openapi_specAPI parameter, schema, or required-field questions
mcp__openaiDeveloperDocs__list_openai_docsBrowse or discover docs pages without a clear query
https://developers.openai.com/api/docs/guides/latest-model.mdAny “latest/best/current model” question
scripts/fetch-codex-manual.mjsBroad Codex self-knowledge questions (runs first)
references/latest-model.mdFallback when the live latest-model page is unreachable
references/upgrade-guide.mdFallback for model upgrade and upgrade-planning requests
references/prompting-guide.mdFallback for prompt rewrites and prompt-behavior upgrades

​
Source priority rules

1

Codex self-knowledge path

For questions about Codex itself, run scripts/fetch-codex-manual.mjs first to get a fresh, cached copy of the Codex manual and its section outline. Use the outline to target the right section, then answer from it.
2

Non-Codex docs path

For all other OpenAI docs questions, call mcp__openaiDeveloperDocs__search_openai_docs, then fetch the most relevant page with mcp__openaiDeveloperDocs__fetch_openai_doc.
3

Model selection path

Fetch https://developers.openai.com/api/docs/guides/latest-model.md live. If unavailable, fall back to the bundled references/latest-model.md and disclose the fallback.
4

Official web fallback

Used only after MCP tools return no meaningful results. Restricted to developers.openai.com and platform.openai.com.

​
Latest model reference

The bundled references/latest-model.md lists recommended model IDs by use case. Always verify against live docs before repeating any of these to a user.
Model IDBest for
gpt-5.5Latest/default text and reasoning; most new apps including coding and tool-heavy workflows
gpt-5.5-proMaximum reasoning or quality when latency and cost matter less
gpt-5.4Previous default text and reasoning; existing GPT-5.4 integrations
gpt-5.4-miniLower-cost testing and lighter production workflows
gpt-5.4-nanoHigh-throughput simple tasks and classification
gpt-5.3-codexAgentic coding, code editing, tool-heavy coding
gpt-5.1-codex-miniCost-optimized coding workflows
gpt-image-1.5Best image generation and editing quality
gpt-image-1-miniCost-optimized image generation
gpt-4o-mini-ttsText-to-speech
gpt-4o-mini-transcribeFast, cost-efficient speech-to-text
gpt-realtime-1.5Realtime voice and multimodal sessions
gpt-realtime-miniCost-optimized realtime sessions
gpt-audioChat Completions audio input and output
gpt-audio-miniCost-optimized Chat Completions audio workflows
sora-2Faster iteration and draft video generation
sora-2-proHigher-quality production video
omni-moderation-latestText and image moderation
text-embedding-3-largeHigher-quality retrieval embeddings
text-embedding-3-smallLower-cost embeddings

​
Prompting best practices (GPT-5.5)

The bundled references/prompting-guide.md covers prompt patterns for the current generation of models. Key takeaways:
  • Outcome-first prompts: Describe the target outcome, success criteria, and constraints — let the model choose the path.
  • Shorter is often better: Newer models need less step-by-step process narration; over-specified prompts can narrow the search space.
  • Add stopping conditions: Tell the model when enough evidence is enough, and what to do when evidence is missing.
  • Personality blocks: For conversational products, define both personality (tone, warmth) and collaboration style (when to ask questions, how proactive to be) separately.
  • Reserve ALWAYS/NEVER: Use absolute rules only for true invariants (safety, required fields). Use decision rules for judgment calls.
Example personality block for a task-focused assistant: 
# Personality
You are a capable collaborator: approachable, steady, and direct. Assume the user
is competent and acting in good faith. Prefer making progress over stopping for
clarification when the request is already clear enough to attempt.
Example stopping condition: 
Resolve the user query in the fewest useful tool loops, but do not let loop
minimization outrank correctness. After each result, ask: "Can I answer the
user's core request now?" If yes, answer.

​
Model upgrade rules

When you ask for a model string upgrade, Codex keeps changes narrow:
  • Updates active OpenAI API model defaults and directly related prompts only
  • Leaves historical docs, eval baselines, fixtures, provider comparisons, pricing tables, and alias defaults unchanged unless you explicitly ask
  • Reports as blocked if the upgrade needs API-surface changes, schema rewiring, or tool-handler changes beyond a literal model-string swap

​
MCP server dependency

This skill depends on the openaiDeveloperDocs MCP server: 
dependencies:
  tools:
    - type: mcp
      value: openaiDeveloperDocs
      transport: streamable_http
      url: https://developers.openai.com/mcp
If MCP tools are unavailable, Codex will attempt to install the server automatically: 
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
After installation, restart Codex to activate the server.

​
Codex surface selection guide

When deciding where a durable instruction belongs, the skill recommends the smallest matching surface:
SurfaceBest for
Prompt / thread contextOne-off task constraints for the current session
AGENTS.mdRepo-wide conventions, commands, verification steps
.codex/config.tomlTrusted-repo Codex settings (sandbox, MCP, model, hooks)
SkillReusable task workflow with references or scripts
PluginInstallable bundle with skills, tools, MCP, hooks, and assets
MCP server / connectorLive external data or authorized private app data
AutomationScheduled checks, monitors, or follow-up work
HookLifecycle enforcement around tool calls or file edits

Build docs developers (and LLMs) love

Get started for freeTalk to us