openapi · itechmeat — Claude Code skill: what it does, how to install
openapi teaches your coding agent how OAS 3.x documents are built: required fields, operations, schemas, parameters and security.
MIT 125 installs ★ 23 updated 2026-10-24
npx skills add itechmeat/llm-code --skill openapi -a claude-codeWhat openapi does
Five reference files come with the skill: document structure, paths and operations, schemas and data types, parameters with serialization, security. The agent reads them instead of guessing at field names.
The examples are concrete: a User object with format: uuid, allOf for composition, oneOf with discriminator for polymorphism, type arrays for nullable fields since OAS 3.1. A table maps each parameter location (path, query, header, cookie, querystring) to its style (simple, form, matrix, label, deepObject). The skill targets 3.2.0, and that version number is where mistakes start: the openapi field is the spec version, while info.version belongs to your own API. Both are required.
One npx skills add line installs it; the payload is markdown next to SKILL.md. Give every operation its own operationId, because client and server generation from the spec hangs on that key, and duplicates break it.
What it helps with
- write a spec from scratch with the right root fields
- wire OAuth2 or an API key into
securitySchemes - pick a serialization style for an array in
query - build a response model from
allOfandoneOf - check an existing spec before generating a client
Example prompts for the agent
- Add
GET /users/{id}to my OpenAPI 3.2 spec, with a 404 response. - Look over
openapi.yamland tell me which required fields are missing. - Model
PetasoneOfwith apetTypediscriminator.
How to install openapi
1Skills CLI (Vercel)
npx skills add itechmeat/llm-code --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 itechmeat/llm-code --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 itechmeat/llm-code --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 itechmeat/llm-code skills/openapi2Manually: put the files in place
.github/skills/openapi/SKILL.md1Skills CLI (Vercel)
npx skills add itechmeat/llm-code --skill openapi -a gemini-cli2Platform CLI
gemini skills install https://github.com/itechmeat/llm-code --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 itechmeat/llm-code --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 do I install openapi in Claude Code?
Run npx skills add itechmeat/llm-code --skill openapi -a claude-code. The skill lands at ~/.claude/skills/openapi/SKILL.md.
What does the openapi skill do?
It hands the agent references on OAS 3.x document structure, operations, schemas, parameters and security schemes, so spec edits follow the spec rather than the model's memory.
Which OpenAPI version does it target?
3.2.0. Nullable fields use the type-array form from 3.1+, and the openapi field stays separate from info.version.
Source text
SKILL.md · MIT
---
name: openapi
description: "OpenAPI Specification (OAS 3.x): document structure, paths, operations, schemas, parameters, security schemes, and validation. Use when writing, reading, or validating OpenAPI specs, designing REST API schemas, or working with OAS 3.x document structure. Keywords: OpenAPI, OAS, Swagger, REST API, schemas."
metadata:
version: "3.2.1"
release_date: "2026-09-10"
---
# OpenAPI Specification
This skill provides guidance for working with OpenAPI Specification (OAS) documents.
**Current version:** OpenAPI 3.2.0 (September 2025)
## Quick Navigation
- Document structure: `references/document-structure.md`
- Operations & paths: `references/operations.md`
- Schemas & data types: `references/schemas.md`
- Parameters & serialization: `references/parameters.md`
- Security: `references/security.md`
## When to Use
- Creating a new OpenAPI specification document
- Describing HTTP API endpoints
- Defining request/response schemas
- Configuring API security (OAuth2, API keys, JWT)
- Validating an existing OpenAPI document
- Generating client/server code from specs
## Document Structure Overview
An OpenAPI document MUST have either an OpenAPI Object or Schema Object at the root.
### Required Fields
```yaml
openapi: 3.2.0 # REQUIRED: OAS version
info: # REQUIRED: API metadata
title: My API
version: 1.0.0
```
### Complete Structure
```yaml
openapi: 3.2.0
info:
title: Example API
version: 1.0.0
description: API description (supports CommonMark)
servers:
- url: https://api.example.com/v1
paths:
/resources:
get:
summary: List resources
responses:
"200":
description: Success
components:
schemas: {}
parameters: {}
responses: {}
securitySchemes: {}
security:
- apiKey: []
tags:
- name: resources
description: Resource operations
```
## Core Objects Reference
### Info Object
```yaml
info:
title: Example API # REQUIRED
version: 1.0.0 # REQUIRED (API version, NOT OAS version)
summary: Short summary
description: Full description (CommonMark)
termsOfService: https://example.com/terms
contact:
name: API Support
url: https://example.com/support
email: [email protected]
license:
name: Apache 2.0
identifier: Apache-2.0 # OR url (mutually exclusive)
```
### Server Object
```yaml
servers:
- url: https://api.example.com/v1
description: Production
- url: https://{environment}.example.com:{port}/v1
description: Configurable
variables:
environment:
default: api
enum: [api, staging, dev]
port:
default: "443"
```
### Path Item Object
```yaml
/users/{id}:
summary: User operations
parameters:
- $ref: "#/components/parameters/userId"
get:
operationId: getUser
responses:
"200":
description: User found
put:
operationId: updateUser
requestBody:
$ref: "#/components/requestBodies/UserUpdate"
responses:
"200":
description: User updated
```
### Operation Object
```yaml
get:
tags: [users]
summary: Get user by ID
description: Returns a single user
operationId: getUserById # MUST be unique across all operations
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"404":
description: Not found
security:
- bearerAuth: []
deprecated: false
```
## Schema Recipes
### Basic Object
```yaml
components:
schemas:
User:
type: object
required: [id, email]
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
age:
type: integer
minimum: 0
```
### Composition with allOf
```yaml
ExtendedUser:
allOf:
- $ref: "#/components/schemas/User"
- type: object
properties:
role:
type: string
enum: [admin, user, guest]
```
### Polymorphism with oneOf
```yaml
Pet:
oneOf:
- $ref: "#/components/schemas/Cat"
- $ref: "#/components/schemas/Dog"
discriminator:
propertyName: petType
mapping:
cat: "#/components/schemas/Cat"
dog: "#/components/schemas/Dog"
```
### Nullable and Optional
```yaml
# OAS 3.1+ uses JSON Schema type arrays
properties:
nickname:
type: [string, "null"] # nullable
```
## Parameter Locations
| Location | `in` value | Notes |
| ------------ | ------------- | ----------------------------------- |
| Path | `path` | MUST be required: true |
| Query | `query` | Standard query parameters |
| Query string | `querystring` | Entire query string as single param |
| Header | `header` | Case-insensitive names |
| Cookie | `cookie` | Cookie values |
### Parameter Styles
| Style | `in` | Type | Example (color=blue,black) |
| ---------- | ----- | ---------------------- | -------------------------- |
| simple | path | array | blue,black |
| form | query | primitive/array/object | color=blue,black |
| matrix | path | primitive/array/object | ;color=blue,black |
| label | path | primitive/array/object | .blue.black |
| deepObject | query | object | color[R]=100&color[G]=200 |
## Security Schemes
### API Key
```yaml
components:
securitySchemes:
apiKey:
type: apiKey
in: header # header, query, or cookie
name: X-API-Key
```
### Bearer Token (JWT)
```yaml
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
```
### OAuth2
```yaml
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.example.com/authorize
tokenUrl: https://auth.example.com/token
scopes:
read:users: Read user data
write:users: Modify user data
```
### Apply Security
```yaml
# Global (all operations)
security:
- bearerAuth: []
# Per-operation
paths:
/public:
get:
security: [] # Override: no auth required
/protected:
get:
security:
- oauth2: [read:users]
```
## Reference Object
Use `$ref` to avoid duplication:
```yaml
# Reference within same document
$ref: '#/components/schemas/User'
# Reference to external file
$ref: './schemas/user.yaml'
$ref: './common.yaml#/components/schemas/Error'
```
## Components Object
Reusable building blocks:
```yaml
components:
schemas: # Data models
responses: # Reusable responses
parameters: # Reusable parameters
examples: # Reusable examples
requestBodies: # Reusable request bodies
headers: # Reusable headers
securitySchemes: # Security definitions
links: # Links between operations
callbacks: # Webhook definitions
pathItems: # Reusable path items
```
## Best Practices Checklist
- [ ] Include `operationId` for all operations (unique, programming-friendly)
- [ ] Use `$ref` for reusable components
- [ ] Add meaningful `description` fields (supports CommonMark)
- [ ] Define all possible response codes
- [ ] Include `examples` for complex schemas
- [ ] Use `tags` to group related operations
- [ ] Mark deprecated operations with `deprecated: true`
- [ ] Use semantic versioning for `info.version`
## Critical Prohibitions
- Do NOT omit `openapi` and `info` fields (they are REQUIRED)
- Do NOT use duplicate `operationId` values
- Do NOT mix `$ref` with sibling properties in Reference Objects
- Do NOT use path parameters without `required: true`
- Do NOT use implicit OAuth2 flow in new APIs (deprecated)
- Do NOT forget security for protected endpoints
## Validation
### File Naming
- Entry document: `openapi.json` or `openapi.yaml` (recommended)
- Format: JSON or YAML (equivalent)
- All field names are case-sensitive
### Common Validation Errors
| Error | Fix |
| -------------------------- | ----------------------------------------------------- |
| Missing required field | Add `openapi`, `info.title`, `info.version` |
| Invalid operationId | Use unique, valid identifier |
| Path parameter not in path | Ensure `{param}` matches parameter name |
| Duplicate path template | Remove conflicting `/users/{id}` vs `/users/{userId}` |
| Invalid $ref | Check URI syntax and target existence |
## Links
- [Documentation](https://spec.openapis.org/oas/latest.html)
- [Releases](https://github.com/OAI/OpenAPI-Specification/releases)
- [GitHub](https://github.com/OAI/OpenAPI-Specification)
- [Learning Portal](https://learn.openapis.org/)
© itechmeat · MIT · itechmeat/llm-code
Similar skills
All skills for Backend and APIs →openapi by other authors comes first.