Ghid operator pentru skill-ul OpenAI Docs

Ce face

openai-docs este ruta pentru întrebări despre construirea cu produse și API-uri OpenAI, Codex, alegerea suprafeței Codex potrivite, selecția modelului, migrarea între modele și upgrade-ul prompturilor.

Scopul lui este simplu: răspunsuri bazate pe documentația oficială OpenAI, cu citări, fără ghicit. Pentru întrebări non-Codex folosește prioritar Docs MCP: mcp__openaiDeveloperDocs__search_openai_docs și mcp__openaiDeveloperDocs__fetch_openai_doc. Pentru API reference, schemă, parametri sau câmpuri obligatorii, verifică și mcp__openaiDeveloperDocs__get_openapi_spec, când există.

Pentru Codex, ruta este separată: întrebările largi despre comportament, setup, configurare, extensii, skill-uri, plugin-uri, MCP, hooks, AGENTS.md, automatizări, suprafețe sau stare locală folosesc mai întâi manualul Codex prin helper-ul skill-ului.

All guides

Când îmi folosește

Folosește-l pentru întrebări de tipul:

„Cum construiesc X cu OpenAI?” „Ce API aleg pentru un workflow agentic?” „Care e diferența dintre Responses API și Chat Completions API?” „Ce model OpenAI aleg pentru cazul meu?” „Cum migrez prompturile către un model mai nou?” „Ce suprafață Codex e potrivită aici?” „Codex suportă configurația asta?”

Acoperă explicit:

Apps SDK: aplicații ChatGPT cu UI web component și server MCP. Responses API: endpoint unificat pentru interacțiuni stateful, multimodale, cu tools. Chat Completions API: răspunsuri generate dintr-o listă de mesaje conversaționale. Codex: agent de coding pentru scriere, înțelegere, review și debugging. gpt-oss: modele OpenAI open-weight de reasoning, sub Apache 2.0. Realtime API: experiențe multimodale low-latency, inclusiv speech-to-speech. Agents SDK: toolkit pentru aplicații agentice cu tools, context, handoff, streaming și tracing.

Dacă cererea presupune build, run, configurare, debugging sau implementarea unei aplicații ori unelte care folosește API OpenAI, trebuie rezolvat mai întâi gate-ul de API key prin skill-ul de credentiale disponibil în runtime. Abia apoi revii aici pentru documentație curentă.

Cum îl invoc / declanșez

Nu există o comandă universală publică de tip „rulează openai-docs”. Declanșatorul este intenția: întreabă despre docs OpenAI, API-uri OpenAI, Codex, model selection, model migration sau prompt upgrade, iar runtime-ul ar trebui să routeze cererea către openai-docs.

Pentru Codex self-knowledge, helper-ul canonic este:

node <skill-dir>/scripts/fetch-codex-manual.mjs

Cu cache suprascris:

node <skill-dir>/scripts/fetch-codex-manual.mjs --cache-dir <cache-dir>

<skill-dir> trebuie rezolvat de runtime către directorul real al skill-ului. Nu se ghicește. Helper-ul produce manualul local și outline-ul lui, iar outline-ul indică secțiunile de citit.

Dacă Docs MCP lipsește, runtime-ul poate încerca instalarea serverului oficial:

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

Dacă instalarea cere permisiuni mai largi, escaladarea trebuie justificată clar. Dacă și asta eșuează, operatorul trebuie să ruleze comanda și să repornească Codex. Nu se inventează disponibilitate.

Exemplu practic

Întrebare: „Vreau să construiesc un asistent care folosește tools și păstrează context. Folosesc Chat Completions sau Responses API?”

Ruta corectă:

1. Caută în Docs MCP.
2. Fetch-uiește pagina relevantă înainte de răspuns.
3. Dacă apar parametri sau request shape, verifică OpenAPI spec când există.
4. Răspunde din documentație, nu din memorie.
5. Dacă depinde de use case, explică trade-off-ul.

Un răspuns bun ar recomanda Responses API pentru interacțiuni stateful, multimodale, cu tools și workflow-uri agentice. Chat Completions rămâne descris ca API pentru răspunsuri generate dintr-o conversație reprezentată ca listă de mesaje. Diferența trebuie ancorată în sursă, nu în folclor tehnic.

Output / unde aterizează

Output-ul este operator-facing: explicație, comparație, exemplu, ghid sau recomandare tehnică. Pentru întrebări de docs, include citări din documentația oficială folosită. Pentru întrebări de API shape, verifică împotriva OpenAPI spec când instrumentul există.

Pentru Codex, helper-ul poate produce manual local și outline. Acestea sunt surse de lucru pentru sesiune, nu artefacte publice de publicat automat.

Pentru surface selection Codex, forma recomandată este: recomandare, de ce, ce să eviți, sursa folosită.

Limite / gotchas

Nu folosi web search general ca primă sursă. Fallback-ul de browsing este limitat la domenii oficiale OpenAI și doar după ce Docs MCP sau manualul Codex sunt indisponibile ori nefolositoare.

Pentru model-selection, „latest model” sau default model, fetch-uiește mai întâi https://developers.openai.com/api/docs/guides/latest-model.md. Dacă nu e disponibil, folosește fallback-ul inclus și spune explicit că ai folosit fallback.

Dacă utilizatorul cere o țintă explicită, de exemplu „migrează la GPT-5.4”, păstrează ținta cerută chiar dacă ghidul latest indică alt model. Ghidarea mai nouă poate fi menționată ca opțională, nu ca înlocuitor.

Nu confunda API key auth cu acces ChatGPT, cloud task, connector sau plugin. Pentru erori de acces, verifică pe straturi: instalare, activare, autorizare, MCP, restart, politică workspace și disponibilitate pe suprafața cerută.

Nu inventa funcții, rollout-uri, entitlement-uri, slugs private sau disponibilitate curentă. Dacă documentația nu stabilește afirmația, spune asta. Documentația oficială bate memoria. Mereu.