home / skills / am-will / codex-skills / openai-docs-skill

openai-docs-skill skill

safe

This skill helps you access up-to-date OpenAI docs via the MCP server to fetch precise guidance for APIs, SDKs, and migrations.

This is most likely a fork of the openai-docs skill from openclaw

npx playbooks add skill am-will/codex-skills --skill openai-docs-skill

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.0 KB

---
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

```bash
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

1. Discover: `search` with a focused query. If unsure, use `list` to browse.
2. Read: `fetch` the most relevant URL (optionally add an anchor).
3. 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.

Environment:
- `MCP_URL`: override the default MCP endpoint.

Overview

This skill queries the OpenAI developer documentation MCP server from the shell so you always get authoritative, up-to-date guidance for the OpenAI platform. It uses a lightweight CLI wrapper (scripts/openai-docs-mcp.sh) to search, list, and fetch specific docs or API schemas. Use it whenever precision about endpoints, parameters, limits, or migrations is required.

How this skill works

Invoke the CLI wrapper to run focused searches or browse the docs index, then fetch the exact page or anchor to retrieve markdown text. Typical flow: search (or list) to discover the best doc page, then fetch that URL or anchor for quoted text and the official doc URL. The wrapper also exposes endpoints and OpenAPI schema fetching for code samples and precise parameter definitions.

When to use it

When implementing or debugging OpenAI API calls (Responses, Chat Completions, Realtime, etc.).
When upgrading or migrating between API versions or SDK releases.
When you need exact parameter names, request/response schemas, or rate limits.
When generating code samples that must match official examples or OpenAPI schemas.
When verifying MCP-integrations, tools, or server capabilities before deploying.

Best practices

Always run search first to locate the most relevant doc, then fetch the exact URL or anchor for quoting.
Surface the original doc URL in your answers so others can verify and follow official guidance.
Prefer fetch of an anchor when you only need a small section (parameters, examples, or migration steps).
Use the endpoints and openapi subcommands to obtain authoritative schema and language-specific code samples.
Do not rely on memory for policy, limits, or deprecated behaviors—always confirm with a fresh fetch.

Example use cases

Find the exact request and response schema for the Responses API and include the doc URL in your implementation notes.
Locate migration instructions for moving from Chat Completions to Responses and quote the steps verbatim.
Fetch OpenAPI schemas to auto-generate client code or validate parameter types before releasing SDK updates.
Verify rate limits and billing-related parameters prior to load testing or production rollout.
Retrieve ChatGPT Apps SDK examples to ensure app integration follows the latest method signatures.

FAQ

Which CLI script should I run?

Use scripts/openai-docs-mcp.sh; it wraps curl and jq against the MCP server.

How do I get schema or code samples?

Use the openapi subcommand to fetch endpoint schemas and optional language-specific code samples.

Can I override the MCP endpoint?

Yes—set the MCP_URL environment variable to point to a different MCP server.