Codex skills for OpenAPI and REST
These skills treat the OpenAPI document as the contract: design it first, lint it with Spectral or Redocly, diff it with oasdiff, generate clients from it and contract-test the running service against it. Codex standardises errors on RFC 9457 Problem Details, captures documentation examples from a real server instead of inventing them, and fails CI when generated code drifts from the spec.
Start with these 3
- OpenAPI-First The spec leads, the server proves it matches Codex treats openapi.yaml as the contract: it designs paths and components in the spec first, lints them against a Spectral or Redocly style guide, diffs the bundle against main with oasdiff, regenerates server types so handlers fail to compile when they drift, and contract-tests the running service with Schemathesis or response validation.
- OpenAPI Client Generation Typed clients from the spec, regenerated in one command Codex makes the OpenAPI spec generator-ready first, using a bundled checker for missing or duplicate operationIds, inline schemas and broken refs, then picks the lightest generator for the stack and pins it. Auth, retries and error mapping live in a wrapper instead of edited generated files, and CI fails when the committed client drifts from the spec.
- API Design Review Catch contract mistakes before the first client Codex reviews the contract rather than the code: it lints OpenAPI with Redocly or Spectral, diffs breaking changes with oasdiff, buf breaking or GraphQL Inspector, then runs design passes for resource model, error shape, pagination, idempotency, evolution and authorization. Each blocker names the exact path or field, the client-facing consequence and a corrected contract snippet.
General skills with OpenAPI and REST guidance
Not built around OpenAPI and REST, but they include steps or tools for it. Not part of the install-all command.
-
ASP.NET Core
Typed results, honest DI lifetimes, lean EF Core -
AWS API Gateway
Pick the right API type, then lock every route -
Figma to Code
Match the frame using your own components and tokens -
PayPal Checkout
Server-side PayPal orders that capture exactly once -
Jira Automation
Bulk-edit Jira safely, from JQL to proof -
Salesforce API
Upsert by external ID, bulk-load without burning limits -
Zoom API
Create meetings and trust every Zoom webhook -
DocuSign and Dropbox Sign
Contracts signed in-app, status from verified webhooks
Every OpenAPI and REST skill in one command
Installs these 7 into ~/.agents/skills/. Add --project after -- to install into the current repository instead.
The installer is a 104-line POSIX shell script. It fetches the skills you name from codexskills.dev and unpacks each into its own folder in your skills directory. No sudo, no telemetry, and every skill page shows the full SKILL.md first. Read install.sh
curl -fsSL codexskills.dev/install.sh | sh -s -- openapi-first openapi-client-generation api-design-review rest-api-design problem-details-errors contract-testing api-documentation OpenAPI and REST FAQ
Is there a Codex skill for design-first OpenAPI 3.1 development?
OpenAPI-First makes openapi.yaml the source of truth, defaulting to OpenAPI 3.1 for new specs. It lints with Spectral or Redocly CLI, compares the bundled spec against the base branch with oasdiff breaking, regenerates server types so handlers fail to compile when they drift, and contract-tests the running server with Schemathesis. It also warns against keeping a hand-written spec alongside framework annotations that emit a second one.
Can Codex generate a typed API client from an OpenAPI spec?
OpenAPI Client Generation first makes the spec generator-ready with a bundled checker for missing or duplicate operationIds, inline schemas and broken refs. It then picks and pins a generator for the stack, such as openapi-typescript with openapi-fetch, Hey API, Orval, openapi-python-client or oapi-codegen. Auth, retries and error mapping go in a wrapper rather than edited generated files, and CI fails when the committed client drifts from the spec.
How should a REST API return errors?
Problem Details Errors routes every failure through one mapper that emits RFC 9457 application/problem+json, with validation errors as JSON Pointer lists, 429s carrying Retry-After and 5xx bodies that include a trace ID but no internals. It works with Express, Fastify, FastAPI, Spring Boot, ASP.NET Core and Go. REST API Design adds the status-code decision table that keeps errors out of 200 responses.
How do I install all 7 OpenAPI and REST skills at once?
Pass every name to the installer in one command: curl -fsSL https://codexskills.dev/install.sh | sh -s -- openapi-first openapi-client-generation api-design-review rest-api-design problem-details-errors contract-testing api-documentation. Add --project right after -- to put them in the current repository's .agents/skills/ so your team gets them too.
Which OpenAPI and REST skill should I try first?
OpenAPI-First is the closest fit for most OpenAPI and REST work. Mention it with $openapi-first in a prompt to load it on purpose; after that, Codex picks it up on its own whenever a task matches.