playbooks

home / skills / openclaw / skills / openai-docs

openai-docs skill

/skills/am-will/openai-docs

This skill helps you quickly retrieve up-to-date OpenAI API guidance by querying the OpenAI Docs MCP server via CLI for authoritative docs.

npx playbooks add skill openclaw/skills --skill openai-docs

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

Files (3)
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 lets you query the OpenAI developer documentation via the OpenAI Docs MCP server from the shell using a small CLI wrapper. Use it whenever you need authoritative, up-to-date guidance about OpenAI APIs, SDKs, ChatGPT Apps, Realtime, Codex, endpoint schemas, parameters, limits, or migrations. It prioritizes direct fetches from the docs so answers are grounded in official text and source URLs.

How this skill works

The skill calls the MCP server through the provided CLI wrapper script (scripts/openai-docs-mcp.sh) which uses curl and jq against https://developers.openai.com/mcp. Typical flow: search or list to find candidate pages, then fetch a page or a specific anchor to retrieve exact markdown. Responses include the source doc URL so you can verify and follow up on the official page.

When to use it

  • Implementing or debugging OpenAI API calls and you need exact parameter names, request/response formats, or limits.
  • Migrating from older OpenAI endpoints (e.g., Chat Completions → Responses) and you need migration guidance.
  • Generating SDK or OpenAPI client code and you need authoritative schema or code samples.
  • Verifying behavior, error codes, or rate limits against the official documentation.
  • Creating ChatGPT Apps or Realtime integrations and you require up-to-date platform guidance.

Best practices

  • Always run a focused search first, then fetch the most relevant URL or anchor to avoid partial or outdated guidance.
  • Include the fetched doc URL in any recommendations or code you share so others can verify the source.
  • Use list to browse when you’re unsure which doc page covers your topic, then refine with search.
  • Prefer fetching exact anchors for parameter tables or examples to capture precise markdown snippets.
  • Set MCP_URL when you need an alternate MCP endpoint (useful for testing or private mirrors).

Example use cases

  • Search for and fetch the Responses API migration guide to convert Chat Completions code to Responses.
  • Pull the Realtime API endpoint schema and sample WebSocket messages to implement a live client.
  • Fetch SDK-specific examples (Python, Node) for calling the Responses or Chat Completions endpoints.
  • Retrieve rate limit and error handling guidance to implement robust retry logic.
  • Obtain OpenAPI endpoint schemas and generate client stubs with concrete, official examples.

FAQ

Do I need special credentials to use the MCP server?

Typically no extra credentials beyond network access are required for the public MCP endpoint; follow local policies if using a private mirror.

How do I get the exact snippet for a parameter or example?

Use search to find the page, then fetch the page with an anchor to return the specific markdown section; include the URL in your output.