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
npx skills add oakoss/agent-skills --skill openapi -a claude-codeWhat 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.yamlusing 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-code2Manually: put the files in place
~/.claude/skills/openapi/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openapi/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a codex2Manually: put the files in place
.agents/skills/openapi/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a cursor2Manually: put the files in place
.cursor/skills/openapi/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/openapi2Manually: put the files in place
.github/skills/openapi/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/openapiManually: put the files in place
.devin/skills/openapi/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.