feat(openai-docs): add OpenAI Docs plugin#253
Conversation
Add a new local plugin bundling OpenAI's openai-docs skill (from the openai/codex repo sample, Apache-2.0) with the openaiDeveloperDocs remote HTTP MCP server (https://developers.openai.com/mcp). The skill was adapted for Claude Code: Codex-agent-specific content (Codex manual helper, self-knowledge/surface-map sections, `codex mcp add` steps, fetch-codex-manual.mjs, agents/+assets/) was removed, while OpenAI docs MCP guidance, model selection, migration, and prompting guidance were retained. A NOTICE file records the source, Apache-2.0 license, and modifications. - plugins/openai-docs/ — Claude source manifest (.claude-plugin/plugin.json), generated runtime manifests (.codex-plugin/, .cursor-plugin/, root plugin.json, .mcp.json, mcp_config.json), README, and skills/openai-docs/ (SKILL.md, references/, scripts/resolve-latest-model-info.js, LICENSE.txt, NOTICE) - .claude-plugin/marketplace.json — new entry (source of truth) with relevance signals - .agents/plugins/marketplace.json, .cursor-plugin/marketplace.json — generated marketplace entries - release-please-config.json, .release-please-manifest.json — version tracking (1.0.0) - README.md — Built-in Plugins listing
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR adds a new "openai-docs" plugin registered across all marketplace/manifest files (agents, claude, cursor, release manifest, release-please config, README, Codacy excludes). It includes per-agent plugin manifests, MCP server configuration pointing to OpenAI's Developer Docs endpoint, a SKILL.md defining MCP-based documentation workflows, bundled reference guides (latest-model mapping, prompting guide, upgrade guide), license/notice files, and a Node.js script to resolve latest model metadata from markdown. Estimated code review effort: 3 (Moderate) | ~25 minutes ChangesOpenAI Docs Plugin Addition
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 Tessl Skill Review
|
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is moderately efficient but includes some redundancy—source priority, fallback behavior, and model-selection steps are repeated across multiple sections (Workflow Configuration, Workflow, Reference map, Tooling notes, MCP unavailable). Some sections could be consolidated to reduce token usage. |
| actionability | ██░ 2/3 | The skill provides specific MCP tool names, concrete script commands (e.g., node scripts/resolve-latest-model-info.js), and clear URLs to fetch. However, it lacks executable code examples for common tasks like making an API call or performing a doc search, and much of the guidance is procedural prose rather than copy-paste-ready commands or code blocks. |
| workflow clarity | ███ 3/3 | The workflow is well-sequenced with clear decision branches (docs lookup vs model selection vs upgrade), explicit fallback chains (MCP → web search → bundled references with disclosure), validation gates (compatibility checks, freshness checks), and feedback loops (if fetch fails → try MCP → try search → use fallback and disclose). The upgrade workflow in the referenced upgrade-guide.md adds further validation checkpoints. |
| progressive disclosure | ███ 3/3 | The skill provides a clear reference map pointing to bundled files (references/latest-model.md, references/upgrade-guide.md, references/prompting-guide.md) and a script, with the instruction 'Read only what you need.' All referenced paths exist in the bundle, and the main SKILL.md stays at overview level while deferring detailed guidance to the appropriate reference files. |
Overall: This is a well-structured skill with strong workflow clarity and good progressive disclosure across its bundle files. Its main weaknesses are moderate redundancy across sections (source priority and fallback logic appear in multiple places) and a lack of concrete executable examples for common operations like performing a doc search or making an API call. The decision trees and fallback chains are thorough and well-designed.
Suggestions:
- Consolidate the repeated source-priority/fallback logic (appears in 'Source Priority', 'If the MCP server is unavailable', 'Workflow' steps 2/6, and 'Tooling notes') into a single authoritative section to reduce token usage.
- Add a concrete executable example showing a typical MCP tool invocation pattern or a sample API call to improve actionability beyond procedural prose.
To improve your score, point your agent at the Tessl optimization guide. Need help? Jump on our Discord.
Feedback
Report issues with this review at tesslio/skill-review, or send private feedback from your terminal with tessl feedback.
Up to standards ✅🟢 Issues
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the new openai-docs plugin to the marketplace, adding its configuration files, documentation, and a helper script to resolve the latest model info. The review feedback identifies a potential TypeError in the CLI argument parsing of resolve-latest-model-info.js when arguments are missing, and recommends updating the documentation to use bun run instead of executing the script directly with node to align with repository standards.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Confine a CLI/env-supplied local source path to the current working directory before reading it, addressing SonarCloud jssecurity:S8707 (path canonicalized from CLI-controlled data must be validated). The default remote URL path and in-tree reference reads are unaffected. NOTICE updated to record the hardening.
The openai-docs skill is vendored from openai/codex (Apache-2.0). Codacy's heuristic rules (detect-non-literal-fs-filename, detect-object-injection) flag its resolve-latest-model-info.js regardless of validation. Follow the repo's documented convention for vendored code and exclude the skill path, matching the existing skillopt-sleep / external-plugins exclusions.
Greptile SummaryThis PR adds an
Confidence Score: 5/5This PR is safe to merge — it adds a new self-contained plugin with no changes to existing plugin logic. The path-traversal guard in resolve-latest-model-info.js correctly handles both plain local paths and file:// URLs before any file read. The fallback chain in SKILL.md is well-defined. The only findings are a display-name capitalisation nit and a missing Node 18+ runtime note in the README, neither of which affects correctness or security. No files require special attention for merge safety. The references/latest-model.md duplicate row and plugin.json author fields were already called out in prior review threads. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[User asks OpenAI docs question] --> B{SKILL.md trigger}
B --> C[openai-docs skill activates]
C --> D{Question type?}
D -->|Model selection / latest| E[Fetch remote latest-model.md]
E -->|Success| F[Parse model + guide URLs]
E -->|Fail| G[Load references/latest-model.md fallback]
D -->|Model / prompt upgrade| H[Run resolve-latest-model-info.js]
H --> I{source type?}
I -->|https://| J[fetch remote URL]
I -->|file:// or local path| K[Validate vs CWD path-traversal guard]
K -->|Outside CWD| L[Throw error]
K -->|Within CWD| M[fs.readFile]
J --> N[Parse latestModelInfo block]
M --> N
N -->|Found| O[Output JSON: model, migrationGuideUrl, promptingGuideUrl]
N -->|Not found| P[Error - use bundled fallback]
D -->|General docs lookup| Q[mcp__openaiDeveloperDocs__search_openai_docs]
Q --> R[mcp__openaiDeveloperDocs__fetch_openai_doc]
R -->|Unavailable| S[Official-domain web search fallback]
O --> T[Fetch migrationGuideUrl + promptingGuideUrl]
T -->|Fail| U[MCP/search fallback or bundled references]
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[User asks OpenAI docs question] --> B{SKILL.md trigger}
B --> C[openai-docs skill activates]
C --> D{Question type?}
D -->|Model selection / latest| E[Fetch remote latest-model.md]
E -->|Success| F[Parse model + guide URLs]
E -->|Fail| G[Load references/latest-model.md fallback]
D -->|Model / prompt upgrade| H[Run resolve-latest-model-info.js]
H --> I{source type?}
I -->|https://| J[fetch remote URL]
I -->|file:// or local path| K[Validate vs CWD path-traversal guard]
K -->|Outside CWD| L[Throw error]
K -->|Within CWD| M[fs.readFile]
J --> N[Parse latestModelInfo block]
M --> N
N -->|Found| O[Output JSON: model, migrationGuideUrl, promptingGuideUrl]
N -->|Not found| P[Error - use bundled fallback]
D -->|General docs lookup| Q[mcp__openaiDeveloperDocs__search_openai_docs]
Q --> R[mcp__openaiDeveloperDocs__fetch_openai_doc]
R -->|Unavailable| S[Official-domain web search fallback]
O --> T[Fetch migrationGuideUrl + promptingGuideUrl]
T -->|Fail| U[MCP/search fallback or bundled references]
Reviews (2): Last reviewed commit: "chore(openai-docs): apply AI code review..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 21 files
Confidence score: 2/5
- In
plugins/openai-docs/skills/openai-docs/scripts/resolve-latest-model-info.js,file://inputs can bypass the existing traversal guard and read files outside the working directory, which creates a real path-traversal exposure if the source is user-influenced—apply the same canonical path validation used for plain paths before any file URL read, then re-test this code path before merging. - In
plugins/openai-docs/skills/openai-docs/references/latest-model.md,gpt-5.5appears twice with different descriptions, so readers can misinterpret capabilities and make incorrect model choices from the reference—deduplicate or clearly merge the entries so one model ID maps to one unambiguous description before merge.
Architecture diagram
sequenceDiagram
participant User as User/Developer
participant Agent as Claude Code (Agent)
participant Plugin as openai-docs Plugin
participant Script as resolve-latest-model-info.js
participant MCP as OpenAI MCP Server
participant LocalRef as Local References/FS
Note over User,LocalRef: Runtime flow after plugin installation
User->>Agent: Ask about latest model / OpenAI docs
Agent->>Plugin: Activate openai-docs skill (via query matching)
alt Model-selection or latest-model query
Plugin->>Script: Execute resolve-latest-model-info.js --source <URL|path>
alt Source is remote URL
Script->>MCP: Fetch latest-model.md (HTTP GET)
MCP-->>Script: Markdown content
else Source is local file
Script->>LocalRef: Read file (with path traversal guard)
LocalRef-->>Script: File content
end
Script->>Script: Parse latestModelInfo block
alt Parsing successful
Script-->>Plugin: JSON: {model, modelSlug, migrationGuideUrl, promptingGuideUrl}
else Parsing fails
Script-->>Plugin: Error (exit 1)
end
else General docs lookup
Plugin->>MCP: search_openai_docs(query)
MCP-->>Plugin: Relevant doc titles
Plugin->>MCP: fetch_openai_doc(docUrl)
MCP-->>Plugin: Doc content
end
alt MCP tools available
Plugin->>MCP: get migration/prompting guide content via MCP
MCP-->>Plugin: Guidance text
else MCP unavailable
Plugin->>LocalRef: Read bundled fallback references (latest-model.md, upgrade-guide.md, prompting-guide.md)
LocalRef-->>Plugin: Fallback content
Note over Plugin: Discloses fallback usage to user
end
alt Path-traversal guard triggered (local source)
Script->>LocalRef: Resolve and validate path inside cwd
alt path escapes cwd
Script-->>Script: Throw Error: refusing to read outside cwd
Script-->>Plugin: Error
else path safe
Script->>LocalRef: Read file
end
end
Plugin->>Plugin: Assemble answer with citations
Plugin-->>Agent: Signed result (with source attribution)
Agent-->>User: Display answer
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
- readSource: confine file:// URLs to the working directory too (the guard previously only covered plain paths, so a file:// source could still read arbitrary host files) — Greptile P1 / cubic P1 - parseArgs: throw a clear error when --source/--url/--base-url is given without a value instead of passing undefined downstream — Gemini - NOTICE updated to record the expanded hardening
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces the new openai-docs plugin, which provides authoritative guidance from official OpenAI developer docs, model selection, and prompt migration, integrated via the OpenAI Developer Docs MCP server. The changes include adding marketplace configurations, documentation, reference guides, and a utility script to resolve the latest model information. The review feedback recommends simplifying the path validation logic in the resolution script to prevent directory reading errors, and suggests updating the documentation to run the resolution script via package.json scripts rather than executing the node script directly.
| : source; | ||
| const allowedBase = path.resolve(process.cwd()); | ||
| const resolved = path.resolve(allowedBase, localPath); | ||
| if (resolved !== allowedBase && !resolved.startsWith(allowedBase + path.sep)) { |
There was a problem hiding this comment.
[MEDIUM] 경로 검증 로직 단순화 및 디렉터리 읽기 방지
Problem: resolved !== allowedBase 조건문은 현재 작업 디렉터리(CWD) 자체를 가리키는 경로를 허용하지만, 디렉터리를 파일로 읽으려고 시도하면 EISDIR 에러가 발생합니다.
Rationale: 안전한 입력 유효성 검사 및 방어적 프로그래밍(Defensive Programming) 원칙에 따라, 디렉터리 자체를 읽으려는 시도를 사전에 차단하고 조건식을 더 직관적으로 단순화하는 것이 좋습니다.
Suggestion: resolved !== allowedBase 체크를 제거하고, allowedBase + path.sep로 시작하는지 여부만 확인하면 디렉터리 자체를 읽는 것을 방지할 수 있습니다.
| if (resolved !== allowedBase && !resolved.startsWith(allowedBase + path.sep)) { | |
| if (!resolved.startsWith(allowedBase + path.sep)) { |
References
- Handle edge cases with guard clauses, and isolate side effects at the boundary. (link)
| - For API reference, schema, parameter, or required-field questions, use `mcp__openaiDeveloperDocs__get_openapi_spec` when available to verify the API shape alongside the relevant guide or reference page. | ||
| - Use `mcp__openaiDeveloperDocs__list_openai_docs` only when you need to browse or discover pages without a clear query. | ||
| - For model-selection, "latest model", or default-model questions, fetch `https://developers.openai.com/api/docs/guides/latest-model.md` first. If that is unavailable, load `references/latest-model.md`. | ||
| - For model upgrades or prompt upgrades, run `node scripts/resolve-latest-model-info.js` only when the target is latest/current/default or otherwise unspecified; otherwise preserve the explicitly requested target. |
There was a problem hiding this comment.
[MEDIUM] package.json에 정의된 스크립트 사용 권장
Problem: 문서에서 node scripts/resolve-latest-model-info.js와 같이 스크립트 파일을 직접 실행하도록 안내하고 있습니다.
Rationale: 특정 런타임 바이너리가 PATH에 존재한다고 가정하는 대신, package.json에 스크립트를 정의하고 bun run <script> 등을 통해 실행하는 것이 일관성을 유지하고 환경 의존성을 줄이는 데 좋습니다.
Suggestion: 해당 스크립트를 package.json의 scripts에 등록하고, 문서에서는 bun run <script> 형태로 실행하도록 수정해 주세요.
| - For model upgrades or prompt upgrades, run `node scripts/resolve-latest-model-info.js` only when the target is latest/current/default or otherwise unspecified; otherwise preserve the explicitly requested target. | |
| - For model upgrades or prompt upgrades, run bun run resolve-model-info only when the target is latest/current/default or otherwise unspecified; otherwise preserve the explicitly requested target. |
References
- Prefer using scripts defined in package.json (e.g., via 'bun run <script>') over executing script files directly in documentation. This maintains consistency and avoids assuming specific runtime binaries are available in the PATH.
| - Find the latest model ID and explicit migration or prompt-guidance links. | ||
| - Prefer explicit links from the latest-model page over derived URLs. | ||
| - For explicit named-model requests, preserve the requested model target. Mention newer remote guidance only as optional. | ||
| - For dynamic latest/current/default upgrades, run `node scripts/resolve-latest-model-info.js`, then fetch both returned guide URLs directly when possible. |
There was a problem hiding this comment.
[MEDIUM] package.json에 정의된 스크립트 사용 권장
Problem: 문서에서 node scripts/resolve-latest-model-info.js와 같이 스크립트 파일을 직접 실행하도록 안내하고 있습니다.
Rationale: 특정 런타임 바이너리가 PATH에 존재한다고 가정하는 대신, package.json에 스크립트를 정의하고 bun run <script> 등을 통해 실행하는 것이 일관성을 유지하고 환경 의존성을 줄이는 데 좋습니다.
Suggestion: 해당 스크립트를 package.json의 scripts에 등록하고, 문서에서는 bun run <script> 형태로 실행하도록 수정해 주세요.
| - For dynamic latest/current/default upgrades, run `node scripts/resolve-latest-model-info.js`, then fetch both returned guide URLs directly when possible. | |
| - For dynamic latest/current/default upgrades, run bun run resolve-model-info, then fetch both returned guide URLs directly when possible. |
References
- Prefer using scripts defined in package.json (e.g., via 'bun run <script>') over executing script files directly in documentation. This maintains consistency and avoids assuming specific runtime binaries are available in the PATH.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plugins/openai-docs/.claude-plugin/plugin.json`:
- Around line 1-25: The Claude manifest for openai-docs is missing the skills
entry, so the new skill bundle will not be included in generated downstream
manifests. Update the plugin manifest in the openai-docs plugin to add the
skills/openai-docs path in the skills list, using the existing manifest
structure and the multi-format generator expectations from
scripts/multi-format.ts, then regenerate the derived files so the new SKILL.md
is surfaced correctly.
In `@plugins/openai-docs/skills/openai-docs/references/latest-model.md`:
- Around line 1-37: The latest model guide currently only provides a markdown
table, but resolve-latest-model-info.js expects parseable latestModelInfo
metadata to determine the model and guide URLs. Add the required latestModelInfo
block/comment to latest-model.md in a format the resolver can read, keeping the
existing table as human-readable fallback. Make sure the metadata includes the
latest model mapping and URL fields so the offline freshness-check path can
resolve entries when the remote doc is unavailable.
In `@plugins/openai-docs/skills/openai-docs/scripts/resolve-latest-model-info.js`:
- Around line 53-63: The remote fetch in resolve-latest-model-info.js has no
timeout, so a slow endpoint can block the skill invocation indefinitely. Update
the fetch logic in the helper that returns response.text() to use an
AbortController with a bounded timeout, and ensure the timeout is cleared after
the request completes. Keep the existing response.ok error handling, but add a
clear timeout-specific failure path so the script fails fast instead of hanging.
In `@plugins/openai-docs/skills/openai-docs/SKILL.md`:
- Around line 1-4: Restore the SKILL.md frontmatter contract by updating the
metadata in openai-docs so it includes the required allowed-tools entry and
changes the skill name to the mandated gerund form. Use the existing frontmatter
block at the top of SKILL.md, keep the description intact, and ensure the skill
metadata matches the format expected by the skill-format rules so the MCP tools
used by the body remain available.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 46893778-a033-4feb-9668-357b692d329e
📒 Files selected for processing (21)
.agents/plugins/marketplace.json.claude-plugin/marketplace.json.codacy.yml.cursor-plugin/marketplace.json.release-please-manifest.jsonREADME.mdplugins/openai-docs/.claude-plugin/plugin.jsonplugins/openai-docs/.codex-plugin/plugin.jsonplugins/openai-docs/.cursor-plugin/plugin.jsonplugins/openai-docs/.mcp.jsonplugins/openai-docs/README.mdplugins/openai-docs/mcp_config.jsonplugins/openai-docs/plugin.jsonplugins/openai-docs/skills/openai-docs/LICENSE.txtplugins/openai-docs/skills/openai-docs/NOTICEplugins/openai-docs/skills/openai-docs/SKILL.mdplugins/openai-docs/skills/openai-docs/references/latest-model.mdplugins/openai-docs/skills/openai-docs/references/prompting-guide.mdplugins/openai-docs/skills/openai-docs/references/upgrade-guide.mdplugins/openai-docs/skills/openai-docs/scripts/resolve-latest-model-info.jsrelease-please-config.json
| { | ||
| "name": "openai-docs", | ||
| "version": "1.0.0", | ||
| "description": "Authoritative, current guidance from official OpenAI developer docs, model selection, and model/prompt migration — backed by the OpenAI Developer Docs MCP server.", | ||
| "author": { | ||
| "name": "OpenAI", | ||
| "url": "https://github.com/openai/codex" | ||
| }, | ||
| "homepage": "https://developers.openai.com", | ||
| "repository": "https://github.com/openai/codex", | ||
| "license": "Apache-2.0", | ||
| "keywords": [ | ||
| "openai", | ||
| "docs", | ||
| "mcp", | ||
| "model-selection", | ||
| "api" | ||
| ], | ||
| "mcpServers": { | ||
| "openaiDeveloperDocs": { | ||
| "type": "http", | ||
| "url": "https://developers.openai.com/mcp" | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Wire the new skill bundle into the Claude manifest.
skills/openai-docs/SKILL.md is added, but this manifest never sets skills, so the multi-format pipeline won't surface the skill in downstream manifests. Add the skills/openai-docs entry here before regenerating the derived files. Based on learnings from scripts/multi-format.ts, skills is the input the generator uses to emit the downstream skill path.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugins/openai-docs/.claude-plugin/plugin.json` around lines 1 - 25, The
Claude manifest for openai-docs is missing the skills entry, so the new skill
bundle will not be included in generated downstream manifests. Update the plugin
manifest in the openai-docs plugin to add the skills/openai-docs path in the
skills list, using the existing manifest structure and the multi-format
generator expectations from scripts/multi-format.ts, then regenerate the derived
files so the new SKILL.md is surfaced correctly.
| # Latest model guide | ||
|
|
||
| This file is a curated helper. Every recommendation here must be verified against current OpenAI docs before it is repeated to a user. | ||
|
|
||
| ## Current model map | ||
|
|
||
| | Model ID | Use for | | ||
| | --- | --- | | ||
| | `gpt-5.5` | Latest/default text and reasoning model for most new apps, including coding and tool-heavy workflows | | ||
| | `gpt-5.5-pro` | Maximum reasoning or quality when latency and cost matter less | | ||
| | `gpt-5.4` | Previous default text and reasoning model; use for existing GPT-5.4 integrations | | ||
| | `gpt-5.4-mini` | Lower-cost testing and lighter production workflows | | ||
| | `gpt-5.4-nano` | High-throughput simple tasks and classification | | ||
| | `gpt-5.5` | Explicit no-reasoning text path via `reasoning.effort: none` | | ||
| | `gpt-4.1-mini` | Cheaper no-reasoning text | | ||
| | `gpt-4.1-nano` | Fastest and cheapest no-reasoning text | | ||
| | `gpt-5.3-codex` | Agentic coding, code editing, and tool-heavy coding workflows | | ||
| | `gpt-5.1-codex-mini` | Cheaper coding workflows | | ||
| | `gpt-image-2` | Best image generation and edit quality | | ||
| | `gpt-image-1.5` | Less expensive image generation and edit quality | | ||
| | `gpt-image-1-mini` | Cost-optimized image generation | | ||
| | `gpt-4o-mini-tts` | Text-to-speech | | ||
| | `gpt-4o-mini-transcribe` | Speech-to-text, fast and cost-efficient | | ||
| | `gpt-realtime-1.5` | Realtime voice and multimodal sessions | | ||
| | `gpt-realtime-mini` | Cheaper realtime sessions | | ||
| | `gpt-audio` | Chat Completions audio input and output | | ||
| | `gpt-audio-mini` | Cheaper Chat Completions audio workflows | | ||
| | `sora-2` | Faster iteration and draft video generation | | ||
| | `sora-2-pro` | Higher-quality production video | | ||
| | `omni-moderation-latest` | Text and image moderation | | ||
| | `text-embedding-3-large` | Higher-quality retrieval embeddings; default in this skill because no best-specific row exists | | ||
| | `text-embedding-3-small` | Lower-cost embeddings | | ||
|
|
||
| ## Maintenance notes | ||
|
|
||
| - This file will drift unless it is periodically re-verified against current OpenAI docs. | ||
| - If this file conflicts with current docs, the docs win. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Add parseable latestModelInfo metadata.
resolve-latest-model-info.js only consumes a latestModelInfo block/comment. This table-only fallback gives the resolver nothing to parse, so the offline freshness-check path cannot resolve the model or guide URLs when the remote doc is unavailable.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugins/openai-docs/skills/openai-docs/references/latest-model.md` around
lines 1 - 37, The latest model guide currently only provides a markdown table,
but resolve-latest-model-info.js expects parseable latestModelInfo metadata to
determine the model and guide URLs. Add the required latestModelInfo
block/comment to latest-model.md in a format the resolver can read, keeping the
existing table as human-readable fallback. Make sure the metadata includes the
latest model mapping and URL fields so the offline freshness-check path can
resolve entries when the remote doc is unavailable.
|
|
||
| const response = await fetch(source, { | ||
| headers: { accept: "text/markdown,text/plain,*/*" }, | ||
| }); | ||
|
|
||
| if (!response.ok) { | ||
| throw new Error(`failed to fetch ${source}: ${response.status}`); | ||
| } | ||
|
|
||
| return response.text(); | ||
| } |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Add a timeout to the remote fetch.
The fetch call has no AbortController/timeout. Since the skill invokes this script synchronously (per SKILL.md's "Freshness check" step) to decide which upgrade guide to use, a slow or unresponsive remote endpoint will hang the entire skill invocation with no bound.
⏱️ Proposed fix: add a request timeout
- const response = await fetch(source, {
- headers: { accept: "text/markdown,text/plain,*/*" },
- });
+ const controller = new AbortController();
+ const timeout = setTimeout(() => controller.abort(), 10_000);
+ let response;
+ try {
+ response = await fetch(source, {
+ headers: { accept: "text/markdown,text/plain,*/*" },
+ signal: controller.signal,
+ });
+ } finally {
+ clearTimeout(timeout);
+ }📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const response = await fetch(source, { | |
| headers: { accept: "text/markdown,text/plain,*/*" }, | |
| }); | |
| if (!response.ok) { | |
| throw new Error(`failed to fetch ${source}: ${response.status}`); | |
| } | |
| return response.text(); | |
| } | |
| const controller = new AbortController(); | |
| const timeout = setTimeout(() => controller.abort(), 10_000); | |
| let response; | |
| try { | |
| response = await fetch(source, { | |
| headers: { accept: "text/markdown,text/plain,*/*" }, | |
| signal: controller.signal, | |
| }); | |
| } finally { | |
| clearTimeout(timeout); | |
| } | |
| if (!response.ok) { | |
| throw new Error(`failed to fetch ${source}: ${response.status}`); | |
| } | |
| return response.text(); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugins/openai-docs/skills/openai-docs/scripts/resolve-latest-model-info.js`
around lines 53 - 63, The remote fetch in resolve-latest-model-info.js has no
timeout, so a slow endpoint can block the skill invocation indefinitely. Update
the fetch logic in the helper that returns response.text() to use an
AbortController with a bounded timeout, and ensure the timeout is cleared after
the request completes. Keep the existing response.ok error handling, but add a
clear timeout-specific failure path so the script fails fast instead of hanging.
| --- | ||
| name: "openai-docs" | ||
| description: "Use when the user asks how to build with OpenAI products or APIs, needs up-to-date official OpenAI documentation with citations, help choosing the latest model for a use case, or model-upgrade and prompt-upgrade guidance; use the OpenAI docs MCP tools for docs questions, verify API shape with the OpenAPI spec, and restrict fallback browsing to official OpenAI domains." | ||
| --- |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Restore the skill frontmatter contract.
SKILL.md is missing allowed-tools, and name: "openai-docs" is not in the required gerund form. The skill-format rules call out both, so this plugin may not expose the MCP tools the body relies on.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plugins/openai-docs/skills/openai-docs/SKILL.md` around lines 1 - 4, Restore
the SKILL.md frontmatter contract by updating the metadata in openai-docs so it
includes the required allowed-tools entry and changes the skill name to the
mandated gerund form. Use the existing frontmatter block at the top of SKILL.md,
keep the description intact, and ensure the skill metadata matches the format
expected by the skill-format rules so the MCP tools used by the body remain
available.
Source: Coding guidelines
2 participants
Summary by cubic
Adds the
openai-docsplugin to surface official OpenAI developer docs, model selection, and migration guidance via theopenaiDeveloperDocsMCP server. Expands path validation in the latest‑model resolver (including file://) and improves CLI arg handling; CI excludes vendored skill code in Codacy.New Features
openai-docsplugin (Apache-2.0; NOTICE included) with README and1.0.0release.openaiDeveloperDocsMCP server (https://developers.openai.com/mcp) with tools:search_openai_docs,fetch_openai_doc,list_openai_docs,get_openapi_spec.scripts/resolve-latest-model-info.jsfor latest-model and guide URL resolution..agents,.claude-plugin,.cursor-plugin, plus relevance signals (OpenAI hosts andpackage.jsonopenaidep).Bug Fixes
scripts/resolve-latest-model-info.js: confine reads to the working directory for both plain paths andfile://URLs; throw clear errors when--source/--url/--base-urllack values.plugins/openai-docs/skills/openai-docs/**from Codacy.Written for commit 3e5417a. Summary will update on new commits.
Summary by CodeRabbit
New Features
Documentation
Chores