Skip to main content
skill CX Codex

openapi · oakoss — Claude Code skill: what it does, how to install

Guides the agent in writing OpenAPI 3.1 schemas and generating TypeScript clients. Ideal for REST API contract design and schema validation.

MIT 197 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill openapi -a claude-code
Open on GitHub

What openapi does

The skill teaches the agent how to build REST API specifications under OpenAPI 3.1, which aligns with JSON Schema Draft 2020-12. It covers root document declarations, operations with required operationId, and centralizing shared models inside components/schemas via $ref. For polymorphic models, the agent learns to combine oneOf with discriminator definitions.

When setting up client pipelines, the rules link schemas to openapi-typescript for zero-runtime types and openapi-fetch for requests. A hard technical boundary applies: OpenAPI 3.1 drops nullable: true. The agent enforces type: ["string", "null"] instead.

Do not use this skill for GraphQL or gRPC services. It addresses HTTP REST contracts only. For deep TypeScript type puzzles, the agent hands off work to typescript-patterns.

What it helps with

  • build OpenAPI 3.1 contracts with accurate response codes
  • generate zero-runtime TypeScript types with openapi-typescript
  • refactor inline payload schemas into reusable ref components
  • prevent schema validation errors such as deprecated nullable fields

Example prompts for the agent

  • Write an OpenAPI 3.1 schema for /resources/{id} with error responses
  • Generate TypeScript types from openapi.yaml using openapi-typescript
  • Audit this API specification for OpenAPI 3.1 compliance issues

How to install openapi

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill openapi -a claude-code

2Manually: put the files in place

~/.claude/skills/openapi/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openapi/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about openapi

How to install openapi in Claude Code?

Run npx skills add oakoss/agent-skills --skill openapi -a claude-code. The skill file is placed at ~/.claude/skills/openapi/SKILL.md.

What does the openapi skill do?

It guides the agent through designing OpenAPI 3.1 REST specifications and setting up typed clients. It enforces valid JSON Schema Draft 2020-12 structures and component references.

How does OpenAPI 3.1 handle nullable fields compared to 3.0?

OpenAPI 3.1 completely removes nullable: true. You must declare nullable fields as an array, such as type: ["string", "null"].

Source text

SKILL.md · MIT
---
name: openapi
description: 'OpenAPI 3.1 specification, schema design, and code generation. Use when designing REST APIs, generating TypeScript clients, or creating API documentation. Use for openapi, swagger, api-spec, schema, code-generation, api-docs, openapi-typescript, zod-openapi.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
  source: 'https://spec.openapis.org/oas/v3.1.0'
user-invocable: false
---

# OpenAPI

## Overview

OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation.

**When to use:** Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration.

**When NOT to use:** GraphQL APIs (use the GraphQL schema), gRPC services (use Protocol Buffers), WebSocket-only protocols, internal function calls that never cross a network boundary.

## Quick Reference

| Pattern         | Element                                                 | Key Points                                         |
| --------------- | ------------------------------------------------------- | -------------------------------------------------- |
| Document root   | `openapi`, `info`, `paths`                              | `openapi: '3.1.0'` required at top level           |
| Path item       | `/resources/{id}`                                       | Curly braces for path parameters                   |
| Operation       | `get`, `post`, `put`, `delete`, `patch`                 | Each operation needs `operationId` and `responses` |
| Parameters      | `in: path\|query\|header\|cookie`                       | Path params are always `required: true`            |
| Request body    | `requestBody.content`                                   | Keyed by media type (`application/json`)           |
| Response        | `responses.200.content`                                 | At least one response required per operation       |
| Component ref   | `$ref: '#/components/schemas/Name'`                     | Reuse schemas, parameters, responses               |
| Schema types    | `type: string\|number\|integer\|boolean\|array\|object` | Arrays support `type: ["string", "null"]` in 3.1   |
| Composition     | `oneOf`, `anyOf`, `allOf`                               | Model polymorphism and intersection types          |
| Discriminator   | `discriminator.propertyName`                            | Hint for code generators with `oneOf`/`anyOf`      |
| Security        | `securitySchemes` + top-level `security`                | Bearer, API key, OAuth2, OpenID Connect            |
| Tags            | `tags` on operations                                    | Group operations for documentation                 |
| Type generation | `openapi-typescript`                                    | Zero-runtime TypeScript types from spec            |
| Typed fetch     | `openapi-fetch`                                         | Type-safe HTTP client using generated types        |
| React Query     | `openapi-react-query`                                   | Type-safe React Query hooks from spec              |
| Schema-first    | `zod-openapi`                                           | Generate OpenAPI documents from Zod schemas        |

## Common Mistakes

| Mistake                                    | Correct Pattern                                                                |
| ------------------------------------------ | ------------------------------------------------------------------------------ |
| Using `nullable: true` in 3.1              | Use `type: ["string", "null"]` (3.0 syntax removed)                            |
| Missing `operationId` on operations        | Always set unique `operationId` for code generation                            |
| Path parameter not in `required`           | Path parameters are always required (`required: true`)                         |
| Inline schemas everywhere                  | Extract to `components/schemas` and use `$ref`                                 |
| `allOf` with conflicting `required` fields | Merge `required` arrays; `allOf` unions them                                   |
| Discriminator without shared property      | All schemas in `oneOf`/`anyOf` must include the discriminator property         |
| Empty `description` on responses           | Every response needs a meaningful `description`                                |
| Using `type: object` without `properties`  | Always define `properties` or use `additionalProperties`                       |
| Circular `$ref` chains                     | Break cycles with lazy resolution or restructure schemas                       |
| Mixing 3.0 and 3.1 syntax                  | Choose one version; 3.1 drops `nullable`, changes `exclusiveMinimum` to number |

## Delegation

- **API design review**: Use `Task` agent to audit spec completeness and consistency
- **Type generation**: Use `Explore` agent to find project-specific OpenAPI tooling config
- **Code review**: Delegate to `code-reviewer` agent for generated client usage patterns

> If the `typescript-patterns` skill is available, delegate advanced TypeScript typing questions to it.

## References

- [Schema design: paths, operations, parameters, components, and $ref](references/schema-design.md)
- [Data types: formats, composition, discriminators, and nullable](references/data-types.md)
- [Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI](references/code-generation.md)
- [Documentation: Swagger UI, Redoc, and API docs best practices](references/documentation.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Backend and APIs →

openapi by other authors comes first.

openapi codewithmukesh Configures native OpenAPI generation in .NET 10 without Swashbuckle. Helps the agent handle transformers, TypedResults metadata, and security schemes. CX Codex +1 4,000installs openapi itechmeat openapi teaches your coding agent how OAS 3.x documents are built: required fields, operations, schemas, parameters and security. CX Codex +1 125installs openapi finom This skill shows how Vovk.ts derives an OpenAPI spec from procedures and validation schemas. Use it to document API operations and configure a docs UI such as Scalar. CX Codex +1 ★ 57repo stars openapi-spec-writer curiositech openapi-spec-writer writes OpenAPI 3.0 and 3.1 specifications for REST APIs. Useful for API-first design, contract definition, and setting up Swagger or Redoc documentation. CX Codex +1 175installs spring-boot-openapi-documentation giuseppe-trisciuoglio spring-boot-openapi-documentation — a skill that walks your agent through SpringDoc OpenAPI 3.0 and Swagger UI setup in Spring Boot 3.x projects, annotations included. CX Codex +1 4,200installs openapi-expert personamanagmentlayer openapi-expert guides OpenAPI 3.0 and 3.1 spec design, schema polymorphism, linter rules, and code generation. CX Codex +1 282installs go-openapi eduardo-sl go-openapi enforces spec-first REST development in Go by generating servers and clients via oapi-codegen, validating requests, and detecting breaking API changes. CX Codex +1 ★ 90repo stars openapi-generator patricio0312rev openapi-generator — a skill for Claude Code, Codex, Cursor, and other AI code editors that generates OpenAPI 3.0/3.1 specifications directly from Express, Next.js, Fastify, Hono, or NestJS routes. CX Codex +1 320installs route-to-openapi zebbern route-to-openapi reads route definitions in your source tree and writes an OpenAPI 3.0.3 spec. Useful when an API needs docs and nobody wants to type them out. CX Codex +1 ★ 4,719repo stars

From the same set106

The whole set →
database-security database-security audits the data layer of Supabase, Postgres and Convex apps: RLS coverage, policy holes, service-role leaks, audit logging. Useful before a release or after an incident. CX Codex +1 208installs typescript-patterns Provides advanced strict-mode TypeScript patterns to enforce type safety and stop runtime errors before code runs. CX Codex +1 202installs react-patterns react-patterns is a Claude Code skill that covers React 19 patterns, state choices, data loading with use(), and reducing needless re-renders when building or reviewing components. CX Codex +1 201installs ci-cd-architecture ci-cd-architecture is a Claude Code skill for planning CI/CD pipelines, comparing deployment platforms, and securing GitHub Actions. It supports preparing a project for production or changing its delivery setup. CX Codex +1 199installs css-animation-patterns css-animation-patterns is a Claude Code skill for CSS animation work. It guides agents on composite properties, transitions, and newer motion APIs. CX Codex +1 196installs pnpm-workspace pnpm-workspace teaches coding agents to configure pnpm monorepos and version catalogs. Useful when managing multi-package repositories. CX Codex +1 195installs icon-design icon-design matches UI concepts to semantically correct icons from Lucide, Heroicons, or Phosphor with safe tree-shaking import habits. CX Codex +1 187installs pdf-tools pdf-tools — a skill for Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI that covers the full PDF lifecycle: text and table extraction, generation, modification, form filling and encryption. CX Codex +1 186installs

Project sponsors

Companies that keep this analytics open