Preface¶

When writing OpenAI-related code with Cursor, Codex, or Claude Code, the most common pitfall is not syntax errors, but mismatches between parameter names, model IDs, interface formats, and documentation. Model training data has a cutoff date, and the API iterates very quickly: when the Responses API, Realtime, Apps SDK, or Codex configuration options change, the assistant will still fabricate answers based on old memories. The code may look runnable, but it will throw errors once tested.

OpenAI officially provides two supporting capabilities for this: the read-only Developer Docs MCP service, and the Agent Skill openai-docs that instructs the assistant to “check official documentation before answering”. The Skill is responsible for routing and citation discipline, while the MCP is responsible for pulling the latest pages from sites like developers.openai.com into the context. Using them together is the official recommended combination.

This article is organized based on cross-verification between the SKILL.md of the curated version of openai-docs in the OpenAI repository and the official Docs MCP documentation.

What is this¶

openai-docs is an Agent Skill maintained by OpenAI (in the universal SKILL.md format), with a very clear positioning: When users ask about OpenAI products/API usage, Codex’s own capabilities and interface options, need cited latest official documentation, or model selection or model/prompt upgrades, first obtain evidence via the official Docs MCP, then organize the answer.

Repository link:
https://github.com/openai/skills/tree/main/skills/.curated/openai-docs

Its dependent Docs MCP service endpoint is:
https://developers.openai.com/mcp

Official documentation: https://developers.openai.com/learn/docs-mcp

This MCP is read-only for documentation and will not call the OpenAI API on your behalf. It covers sites including developers.openai.com, platform.openai.com, and learn.chatgpt.com.

The general structure of the Skill package is as follows:

openai-docs/
├── SKILL.md
├── agents/openai.yaml      # Declares dependency on openaiDeveloperDocs MCP
├── assets/
├── references/             # Local fallback references for model selection/upgrades/prompting
│   ├── latest-model.md
│   ├── upgrade-guide.md
│   └── prompting-guide.md
└── scripts/
    ├── fetch-codex-manual.mjs
    └── resolve-latest-model-info.js

Core Features and Highlights¶

According to SKILL.md and agents/openai.yaml, this Skill mainly does the following:

Official Document Priority Retrieval and Citation
For non-Codex OpenAI documentation questions, first use the Docs MCP’s search_openai_docs to find pages, then use fetch_openai_doc to pull the main content before answering. For questions about API formats, schemas, parameters, required fields, etc., get_openapi_spec will also be used to verify the interface shape when available. Use list_openai_docs only when browsing discovery pages.
Codex Self-Knowledge Uses the Manual Link Separately
For questions about Codex configuration, extensions, Skills/Plugins/MCP/Hooks, AGENTS.md, client-side interfaces, and other “what Codex itself is” issues, first run the in-skill script to pull the latest Codex manual (and generate a local outline), instead of searching regular web pages directly. When the manual is insufficient or the helper is unavailable, narrow down the scope to use Docs MCP, and finally allow falling back to official domain web pages only.
Model Selection and Upgrade/Prompt Migration
Questions like “latest models”, “which one to use by default”, “migrate to a certain model”, “how to modify prompts” are taken over by this Skill: first pull the remote latest-model.md; dynamic “latest/current” upgrades will run resolve-latest-model-info.js; when the remote is unavailable, use the fallback files in references/ and disclose that fallback is used. If the user clearly states a target like “migrate to GPT-5.x”, retain that target and only use the updated official guidance as optional instructions.
Source Discipline: Guess Less, Traceable
Take official documents as the source of truth; cite simultaneously when there are document conflicts; say that the content cannot be found when it cannot be retrieved; web page fallback is limited to official domains such as developers.openai.com and platform.openai.com. This directly addresses the pain points of “fabricated parameters and outdated examples”.

Installation and Activation¶

The Skill and MCP are two layers: the Skill tells the assistant how to search; the MCP provides what can be searched. The official Docs MCP page also states: When using Skills, the Docs MCP should be paired with the OpenAI Docs Skill.

1. Configure Docs MCP (Required)¶

Codex (shared configuration for CLI / IDE)

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

Or write to ~/.codex/config.toml:

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

If you want Codex to more stably use the MCP proactively, the official recommendation is to add a guide in the project AGENTS.md, for example: When needing information related to OpenAI API / plugins / ChatGPT / Codex, always prioritize using the OpenAI developer documentation MCP, without verbal reminders each time.

Cursor
Add an HTTP/streamable service pointing to https://developers.openai.com/mcp in the MCP settings, and the name is recommended to be openaiDeveloperDocs (consistent with the Skill declaration).

Claude Code

claude mcp add --transport http openaiDeveloperDocs https://developers.openai.com/mcp

The Skill also stipulates: If the MCP tool is unavailable in the session, the assistant should first try to run the above codex mcp add ... by itself; retry with higher weight if there are permission/sandbox failures; if it still fails, ask the user to install and restart before checking the documentation.

2. Install the openai-docs Skill¶

This Skill follows the universal Agent Skills directory convention and can be reused across tools that support SKILL.md. The directory name must match the name in the frontmatter: openai-docs.

In Codex (official skills repository instructions)
Curated skills can be installed by name using $skill-installer, for example:

$skill-installer openai-docs

You need to restart Codex after installation to load the new Skill. The repository README also mentions that some skills under .system will be automatically installed with newer versions of Codex; this article introduces the publicly curated package at .curated/openai-docs, and the configuration should be based on this directory and SKILL.md in the repository.

In Cursor
Place the entire openai-docs folder into the project or user skill directory, for example:

# Copy after checking out from the repository (adjust the path according to your local clone location)
cp -r skills/.curated/openai-docs .cursor/skills/openai-docs

Cursor will also scan .agents/skills/, ~/.cursor/skills/, ~/.agents/skills/, as well as compatible paths .claude/skills/ and .codex/skills/. You can also manually invoke it via /openai-docs in an Agent conversation (if the client supports calling by name).

In Claude Code

mkdir -p .claude/skills
cp -r skills/.curated/openai-docs .claude/skills/openai-docs

The personal global directory is ~/.claude/skills/openai-docs/.

After copying, confirm that the directory contains at least SKILL.md, as well as scripts/ and references/ (these folders are dependencies for Codex manual pulling and model fallback).

Typical Usage Examples¶

The following types of prompts are most likely to trigger the Skill’s design path (the wording can be adjusted according to your tool habits):

Check API / parameters (via Docs MCP)

Based on the current official documentation for the tool call related fields in the Responses API, first use OpenAI Docs MCP to search and fetch the corresponding page, then provide a runnable minimal example and attach the documentation link.

Verify OpenAPI / required fields

What fields are required when creating a Responses request? Please use `get_openapi_spec` (if available) to cross-check the official reference, and do not fabricate parameter names from memory.

Model Selection

For a proxy task that requires strong multi-step tool calling, recommend the current model according to the official latest-model guide, and explain which page of documentation the selection basis comes from.

Model String / Prompt Upgrade (narrow change)

Migrate the default OpenAI API model in the project to the officially currently recommended version, only change the model default values and directly related prompts; do not modify historical documents, evaluation baselines, pricing tables, etc.

How to Configure Codex Itself

I want to add persistent conventions and MCP to the repository, should I use AGENTS.md, the project .codex/config.toml, or Skill/Plugin? Please answer according to the Codex manual path of openai-docs and provide the basis.

The general workflow of the assistant (constrained by the Skill) for documentation questions is: clarify the question type → for Codex questions, first run node <skill-dir>/scripts/fetch-codex-manual.mjs → for other documentation questions, use short queries (about 2–6 keywords) to search and fetch precise sections → answer with concise citations.

Applicable Scenarios and Notes¶

Suitable For
- When integrating OpenAI APIs (Chat Completions, Responses, Realtime, Agents SDK, Apps SDK, etc.) daily, you need citable latest documentation.
- Selecting or migrating models, and narrowing the scope of prompt modifications according to official guidelines.
- Asking product-oriented questions in the Codex ecosystem, such as “should I write in AGENTS.md or config / Skill / Hook”.
- Teams want AI assistants to reduce hallucinations and make answers traceable to official pages.

Notes
1. Only Skill without MCP: The assistant may only have the local references/ or official domain web page fallback, and timeliness and coverage will be reduced; the official clearly recommends pairing both.
2. MCP is read-only for documentation: It cannot replace real API calls, billing inquiries, or account permission operations.
3. Keep the upgrade scope narrow: The Skill requires that only active model default values and directly related prompts be modified by default; do not modify SDK/IDE/authentication environment migrations, historical examples and eval baselines, etc., unless the user explicitly requests it.
4. Stop when you cannot find the content: For undisclosed model slugs, beta switches, and private privilege paths, answer based on public documentation and indicate uncertainty, instead of expanding the search scope and guessing forcibly.
5. Repository Status: The openai/skills repository README has reminded that this sample repository tends to be historical archiving. You can follow the OpenAI Plugins and Codex documentation for the new Codex plugin/skill release path; however, openai-docs under the curated directory and the Docs MCP official page still reference each other, and you can configure it according to the current SKILL.md and Docs MCP page.

Summary¶

openai-docs turns the “check official documentation first, then speak” into a reusable Agent workflow, while Docs MCP turns the latest documentation into a callable tool. For people writing OpenAI / Codex-related code, this is equivalent to adding a layer of authoritative knowledge外挂 to programming assistants, specifically suppressing outdated memories and fabricated parameters.

Official links:
- Skill: https://github.com/openai/skills/tree/main/skills/.curated/openai-docs
- Docs MCP: https://developers.openai.com/learn/docs-mcp
- Skill usage in API reference: https://developers.openai.com/cookbook/examples/skills_in_api

Integrate Official Documentation for AI Programming Assistants with openai-docs Skill: Say Goodbye to Outdated APIs and Fabricated Parameters