| name | openai-docs |
| description | Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; supersedes docs-lookup for OpenAI-specific questions; prioritize OpenAI docs MCP tools, use bundled references only as helper context, and restrict any fallback browsing to official OpenAI domains. |
| metadata | {"short-description":"Reference official OpenAI docs"} |
| resources | [{"path":"scripts/resolve-latest-model-info.js","kind":"script","description":"Resolve latest model, migration guide, and prompting guide metadata from official docs markdown."},{"path":"references/latest-model.md","kind":"reference","description":"Bundled fallback for latest/current model-selection guidance."},{"path":"references/upgrade-guide.md","kind":"reference","description":"Bundled fallback for model upgrade planning and migration guidance."},{"path":"references/prompting-guide.md","kind":"reference","description":"Bundled fallback for prompt rewrite and prompt-behavior upgrade guidance."}] |
| commands | [{"name":"resolve-latest-model-info","source":"skill","resource_path":"scripts/resolve-latest-model-info.js","example_argv":["node","scripts/resolve-latest-model-info.js"],"purpose":"Resolves latest model and related guide URLs from official docs markdown."}] |
OpenAI Docs
Provide authoritative, current guidance from OpenAI developer docs. Use the
developer-docs MCP tools first when they are available and useful; use official
OpenAI-domain web search as the fallback. This skill owns OpenAI model
selection, model migration, and prompt-upgrade guidance as well as general API
docs lookup.
Source priority
- Search with a compact, title-like query of 2-6 discriminative terms instead
of turning the full user question into a keyword list.
- Use
mcp__openaiDeveloperDocs__search_openai_docs to discover relevant pages
and mcp__openaiDeveloperDocs__fetch_openai_doc to read exact sections.
- For API schema, parameter, or required-field questions, use
mcp__openaiDeveloperDocs__get_openapi_spec when available alongside the
relevant guide or reference page.
- When an official page URL is already known, fetch that page before relying on
search-result summaries.
- Use
mcp__openaiDeveloperDocs__list_openai_docs only when no clear query or
candidate page exists.
- If MCP tools are unavailable or unhelpful, continue with official OpenAI web
sources. Do not install or reconfigure MCP as a side effect of a docs lookup;
offer setup only when the user asks to configure it.
Latest-model route
- Fetch
https://developers.openai.com/api/docs/guides/latest-model.md first
for latest/current/default model questions.
- For a latest/current/default migration, run
node scripts/resolve-latest-model-info.js, then fetch the returned migration
and prompting URLs.
- Treat a non-2xx, empty, whitespace-only, or non-substantive guide response as
unavailable. Try MCP fetch/search or official OpenAI web search for the same
guidance before using bundled fallbacks.
- Preserve explicit targets. If the user asks for GPT-5.4, do not silently
retarget the work to GPT-5.6; mention newer guidance only as optional context.
- If current remote guidance cannot be read, use the bundled references and
disclose that fallback guidance was used.
- If current OpenAI pages disagree, state the conflict and avoid inventing a
single value.
Workflow
- Classify the request as general docs lookup, model selection, model
migration, prompt migration, or broader API/provider implementation work.
- For model migrations, inventory active model usage, reasoning settings,
adjacent prompts, routers, fallbacks, schemas, parsers, tools, and tests.
- Map workload roles rather than replacing every model with the flagship tier.
Preserve historical docs, examples, eval baselines, comparison code,
intentionally pinned fallbacks, and ambiguous usage unless explicitly asked
to change them.
- For GPT-5.5 or GPT-5.4 migrations, preserve the current reasoning effort for
the baseline and test the same setting plus one level lower. Do not guess an
omitted setting when current docs or host behavior are unclear.
- Switch the model and run representative evals before rewriting prompts.
Remove redundant or stale scaffolding one group at a time and add only the
smallest instruction needed for a measured regression.
- Keep optional capabilities such as Pro mode, explicit caching, persisted
reasoning, Programmatic Tool Calling, and multi-agent behavior separate from
the baseline migration unless the user explicitly requests them.
- Do not turn a model-and-prompt upgrade into an SDK, endpoint, provider,
tooling, IDE, plugin, shell, auth, tool-schema, parser, or orchestration
migration without explicit scope.
- Validate user-visible behavior and machine-readable contracts. Report what
changed, what remained pinned, what was not run, and any compatibility
blockers.
Reference map
Read only what you need:
https://developers.openai.com/api/docs/guides/latest-model.md -> current model-selection and "best/latest/current model" questions.references/latest-model.md -> bundled fallback for model-selection and "best/latest/current model" questions.references/upgrade-guide.md -> bundled fallback for model upgrade and upgrade-planning requests.references/prompting-guide.md -> bundled fallback for prompt rewrites and prompt-behavior upgrades.
Quality rules
- Treat OpenAI docs as the source of truth; avoid speculation.
- Keep migration changes narrow and behavior-preserving.
- Prefer prompt-only fixes for prompt-specific regressions; do not rewrite a
working prompt stack wholesale.
- Do not invent pricing, availability, parameters, API changes, or breaking changes.
- Keep quotes short and within policy limits; prefer paraphrase with citations.
- If multiple pages differ, call out the difference and cite both.
- If official docs and repo behavior disagree, state the conflict and stop before making broad edits.
- If docs do not cover the user’s need, say so and offer next steps.
Tooling notes
- Prefer MCP doc tools for OpenAI markdown docs when available, then use
official-domain web search when MCP is unavailable or unhelpful.
- When falling back to web search, restrict to official OpenAI domains (developers.openai.com, platform.openai.com) and cite sources.
