openai-docs-skill

am-will/codex-skills

Query OpenAI's official developer docs via MCP server for API, SDK, and platform guidance.

What is openai-docs-skill?

Access authoritative OpenAI documentation directly through a CLI interface powered by the OpenAI Docs MCP server. Use this whenever you need current, official information about OpenAI APIs, SDKs, endpoints, parameters, or migrations instead of relying on outdated knowledge or unofficial sources.

Search the OpenAI docs index with focused queries to discover relevant pages
Fetch full markdown documentation for specific pages or anchored sections
List available documentation pages to browse the docs index
Retrieve OpenAPI endpoint schemas and code samples in multiple languages
Query endpoint specifications and parameter limits directly from official sources
Surface documentation URLs in responses for clear source attribution

How to install openai-docs-skill

npx skills add https://github.com/am-will/codex-skills --skill openai-docs-skill

Prerequisites

curl and jq installed locally
Access to the OpenAI Docs MCP server at https://developers.openai.com/mcp
Optional: MCP_URL environment variable to override default endpoint

Claude Code

Cursor

Windsurf

Cline

How to use openai-docs-skill

1.Run `scripts/openai-docs-mcp.sh init` to verify server capabilities and connection
2.Use `search <query> [limit]` to find relevant documentation pages (e.g., `search "Chat Completions" 5`)
3.Use `list [limit]` to browse the full documentation index if you're unsure what to search for
4.Run `fetch <url> [anchor]` to retrieve the full markdown for a specific page or section
5.For API schemas, use `endpoints` to list available endpoints or `openapi <endpoint-url>` to fetch OpenAPI specs and code samples
6.Include the documentation URL from your fetch results in your response for source clarity

Use cases

Good for

Implementing Chat Completions or Responses API calls with correct parameters and error handling
Migrating code between OpenAI API versions using official migration guides
Understanding rate limits, pricing tiers, and model availability for production deployments
Generating code samples in specific languages for OpenAI SDK integration
Troubleshooting API authentication, request formatting, or response handling issues

Who it's for

Backend engineers integrating OpenAI APIs into applications
AI/ML developers building with ChatGPT Apps SDK or Codex
DevOps engineers managing OpenAI platform deployments
Technical leads reviewing API documentation for compliance and best practices

openai-docs-skill FAQ

When should I use this skill instead of relying on my training data?

Always use this skill for OpenAI platform work. Official docs are authoritative, current, and change frequently. Your training data may be outdated for API parameters, models, pricing, or endpoints.

How do I find the right documentation page to fetch?

Start with `search` using a focused query like 'Responses API' or 'rate limits'. If unsure, use `list` to browse available pages. The search returns JSON hits ranked by relevance.

Can I fetch just a specific section of a page?

Yes. Use `fetch <url> [anchor]` where the anchor is the section heading. For example: `fetch https://platform.openai.com/docs/guides/migrate-to-responses#authentication`

What if I need code samples in a specific language?

Use `openai <endpoint-url> [lang1,lang2]` to fetch OpenAPI schemas with code samples. Specify languages like 'python,javascript' or use `code-only` flag to get just the samples.

How do I know which OpenAI endpoint to query?

Run `endpoints` to list all available OpenAPI endpoints, then use `openapi <endpoint-url>` to fetch the full schema and code examples for that endpoint.

Full instructions (SKILL.md)

Source of truth, from am-will/codex-skills.

name: openai-docs-skill description: Query the OpenAI developer documentation via the OpenAI Docs MCP server using CLI (curl/jq). Use whenever a task involves the OpenAI API (Responses, Chat Completions, Realtime, etc.), OpenAI SDKs, ChatGPT Apps SDK, Codex, MCP integrations, endpoint schemas, parameters, limits, or migrations and you need up-to-date official guidance.

OpenAI Docs MCP Skill

Overview

Use the OpenAI developer documentation MCP server from the shell to search and fetch authoritative docs. Always do this for OpenAI platform work instead of relying on memory or non-official sources.

Core rules

Always use this skill for OpenAI API/SDK/Apps/Codex questions or when precise, current docs are required.
Query the MCP server via the CLI wrapper in scripts/openai-docs-mcp.sh (do not rely on Codex MCP tools).
Use search or list to find the best doc page, then fetch the page (or anchor) for exact text.
Surface the doc URL you used in your response so sources are clear.

Quick start

scripts/openai-docs-mcp.sh search "Responses API" 5
scripts/openai-docs-mcp.sh fetch https://platform.openai.com/docs/guides/migrate-to-responses

Workflow

Discover: search with a focused query. If unsure, use list to browse.
Read: fetch the most relevant URL (optionally add an anchor).
Apply: summarize and/or quote relevant sections; include the URL.

Script reference

The CLI wrapper is at scripts/openai-docs-mcp.sh and uses curl + jq against https://developers.openai.com/mcp.

Subcommands:

init: initialize and inspect server capabilities.
tools: list available tools on the MCP server.
search <query> [limit] [cursor]: return JSON hits from the docs index.
list [limit] [cursor]: browse docs index.
fetch <url> [anchor]: return markdown for a doc page or section.
endpoints: list OpenAPI endpoints.
openapi <endpoint-url> [lang1,lang2] [code-only]: fetch OpenAPI schema or code samples.