openai-docs

Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with concrete tools, commands, URLs, and citation anchors, and its multi-step workflows are well-sequenced with recovery paths. Its main weakness is verbosity: routing logic is restated across several sections and large blocks are inlined that could be split into references.

Suggestions

Consolidate the repeated routing/cache-dir/fallback guidance that appears in "Source Priority", the Codex "Source Route", "Workflow", and "Reference map" into a single source of truth and cross-reference it.

Move the lengthy Codex source-route procedure and surface map into a dedicated reference file, leaving SKILL.md as a concise routing overview that links to it.

Tighten the Codex "Source Route" prose by converting verbose conditional sentences into a compact decision table or short numbered checklist.

Dimension	Reasoning	Score
Conciseness	The body is prose-heavy and repeats routing logic across "Source Priority", "Codex self-knowledge / Source Route", "Workflow", and "Reference map" (e.g., helper/cache-dir and fallback conditions restated multiple times); it is mostly efficient but carries several padded, over-explained sections, fitting the 3-anchor rather than the lean 4-anchor.	3 / 5
Actionability	It provides exact MCP tool names (`mcp__openaiDeveloperDocs__search_openai_docs`, `get_openapi_spec`), exact URLs, runnable scripts (`node scripts/resolve-latest-model-info.js`, `node <skill-dir>/scripts/fetch-codex-manual.mjs`), concrete install commands, and specific citation anchors—copy-paste ready and covering common cases.	5 / 5
Workflow Clarity	Multi-step processes are clearly sequenced (numbered Codex route, the "If MCP server is missing" recovery, and the "Workflow" list) with explicit checkpoints (helper freshness verification, fetch-failure fallback, restart-then-re-run), but some validation is implicit rather than an explicit validate→fix→retry loop, so it sits below the 5-anchor.	4 / 5
Progressive Disclosure	Clear sectioned overview with a one-level-deep "Reference map" whose referenced files (references/latest-model.md, upgrade-guide.md, prompting-guide.md; scripts/fetch-codex-manual.mjs, resolve-latest-model-info.js) all exist, but substantial bulk (the full Codex source route and surface map) is inlined that could live in separate references, keeping it just below the 5-anchor.	4 / 5
	Total	16 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is comprehensive and trigger-rich, explicitly covering both capabilities and usage conditions with concrete, domain-specific language. Its only weakness is a slight tilt toward implementation phrasing over plain user synonyms.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions—"build with OpenAI products or APIs", "choosing Codex surfaces", "up-to-date official documentation with citations", "choosing the latest model", "model upgrade and prompt-upgrade guidance"—giving comprehensive coverage, so it is not the 4-anchor which implies minor gaps.	5 / 5
Completeness	Explicitly states what the skill does and when to use it via repeated "Use when the user asks…" clauses with concrete trigger phrases, matching the 5-anchor that answers both what and when explicitly.	5 / 5
Trigger Term Quality	Strong natural terms appear ("build with OpenAI products or APIs", "Codex", "latest model", "model upgrade", "prompt-upgrade guidance"), but it leans toward implementation phrasing and omits common synonyms/file extensions, keeping it just below the comprehensive 5-anchor.	4 / 5
Distinctiveness Conflict Risk	Scoped tightly to OpenAI docs, Codex self-knowledge, and model/prompt upgrades with distinct triggers, giving a clear niche and minimal overlap with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: jscraik/Agent-Skills
Path: skills-system/openai-docs/SKILL.md
Commit: b3478dc

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.