Skip to main content
skill CX Codex

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

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

What 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 allOf and oneOf
  • 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.yaml and tell me which required fields are missing.
  • Model Pet as oneOf with a petType discriminator.

How to install openapi

1Skills CLI (Vercel)

npx skills add itechmeat/llm-code --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 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.

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 oakoss Guides the agent in writing OpenAPI 3.1 schemas and generating TypeScript clients. Ideal for REST API contract design and schema validation. CX Codex +1 197installs 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 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 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 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 api-documenter zhaono1 api-documenter — a skill for writing REST and GraphQL API documentation as OpenAPI/Swagger specs. Useful when scattered endpoints need to become one readable file. CX Codex +1 727installs api-reference-documentation secondsky api-reference-documentation turns an OpenAPI spec into a developer-facing API reference: endpoints, auth, request and response examples. Useful for SDK docs and developer portals. CX Codex +1 472installs

From the same set16

The whole set →
changelog Keeps CHANGELOG.md on the Keep a Changelog 1.1.0 spec: six change types, version headers, ISO dates, comparison links at the bottom. CX Codex +1 192installs makefile This skill guides an agent through GNU Make files, targets, recipes, checks, and build tasks. Use it when a project needs repeatable command automation. CX Codex +1 181installs commits This skill guides agents in writing Conventional Commits and marking breaking changes. Use it when commit history feeds changelogs or SemVer. CX Codex +1 178installs skill-master skill-master — a skill that helps you write, validate and benchmark Agent Skills against the agentskills.io spec: folder layout, SKILL.md frontmatter, trigger evals. CX Codex +1 161installs project-creator project-creator scaffolds structured technical documentation in a .project/ directory and guides you through specs, architecture, and user stories. CX Codex +1 113installs vite This skill guides an agent through Vite setup, builds, plugins, HMR, and environment settings when a project needs frontend tooling support. CX Codex +1 111installs fastapi This Claude Code skill guides Python API work with FastAPI. It activates for REST endpoints, Pydantic models, dependency injection, and OAuth2/JWT setup. CX Codex +1 100installs open-meteo This Claude Code skill builds requests for Open-Meteo weather, air-quality, and geocoding APIs. It activates when a task needs forecast data, pollution metrics, or coordinates for a place name. CX Codex +1 100installs

Project sponsors

Companies that keep this analytics open