Skip to main content
skill CX Codex

openapi-expert — Claude Code skill: what it does, how to install

openapi-expert guides OpenAPI 3.0 and 3.1 spec design, schema polymorphism, linter rules, and code generation.

Apache-2.0 282 installs ★ 45 updated 2026-10-12

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

What openapi-expert does

This skill provides patterns for crafting REST API contracts in YAML or JSON. It covers endpoints, parameters, reusable components, and OpenAPI 3.1 capabilities such as webhooks and schema inheritance with oneOf, allOf, and discriminator mappings.

The instructions cover standard developer workflows. The agent receives templates to trigger @openapitools/openapi-generator-cli for TypeScript clients or Python Flask stubs, run Spectral linting rules, and spin up Swagger UI or Redoc.

Executing the code generation or linting commands requires Node.js CLI packages or Docker present on your machine.

What it helps with

  • define webhooks and endpoint schemas under OpenAPI 3.1
  • generate TypeScript Axios clients from openapi.yaml
  • validate API definitions using Spectral CLI rulesets
  • configure polymorphic schemas using discriminator mappings

Example prompts for the agent

  • Define an OpenAPI 3.1 webhook for postCreated with a JSON payload
  • Generate a TypeScript Axios client from openapi.yaml using openapi-generator-cli
  • Create a .spectral.yaml ruleset enforcing operationId on all paths

How to install openapi-expert

1Skills CLI (Vercel)

npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-code

2Manually: put the files in place

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

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

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

Questions about openapi-expert

How to install openapi-expert in Claude Code?

Run npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-code in your terminal. The configuration is stored at ~/.claude/skills/openapi-expert/SKILL.md.

What does openapi-expert do?

It guides the agent through designing OpenAPI 3.0 and 3.1 specifications, setting up linters, and running code generators.

Which external tools does openapi-expert rely on?

It includes commands for @openapitools/openapi-generator-cli, @stoplight/spectral-cli, and official Docker containers for Swagger UI and Redoc.

Source text

SKILL.md · Apache-2.0
---
name: openapi-expert
version: 1.1.0
description: >-
  Expert-level OpenAPI/Swagger specification for API design, documentation, and code
  generation. Use when the user mentions swagger, API specs, REST, API design, or
  documentation, or when the task involves OpenAPI Specification, Webhooks, or
  Polymorphism.
category: api
tags: [openapi, swagger, api-spec, rest, api-design, documentation]
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(openapi:*, swagger:*)
---

# OpenAPI Expert

Expert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.

## Core Concepts

### OpenAPI Specification (OAS)

- API description format (YAML/JSON)
- Version 3.1 (latest) and 3.0
- Machine-readable API contracts
- Automatic documentation generation
- Client/server code generation
- API validation and testing

### Key Components

- Paths (endpoints)
- Operations (HTTP methods)
- Parameters
- Request/Response bodies
- Schemas (data models)
- Security schemes
- Components (reusable objects)

## Advanced Features

### Webhooks (OpenAPI 3.1)

```yaml
webhooks:
  postCreated:
    post:
      summary: Post created webhook
      operationId: onPostCreated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Webhook received
```

### Polymorphism (oneOf/anyOf/allOf)

```yaml
components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

    Cat:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [cat]
            meow:
              type: string

    Dog:
      allOf:
        - $ref: '#/components/schemas/PetBase'
        - type: object
          properties:
            petType:
              type: string
              enum: [dog]
            bark:
              type: string
```

## Code Generation

```bash
# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client

# Generate Python Flask server
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python-flask \
  -o ./server

# Generate Java Spring server
openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server
```

## Validation

```bash
# Install Spectral (OpenAPI linter)
npm install -g @stoplight/spectral-cli

# Validate spec
spectral lint openapi.yaml

# Custom ruleset
# .spectral.yaml
extends: spectral:oas
rules:
  operation-tags: error
  operation-operationId: error
  no-$ref-siblings: error
```

## Documentation Generation

```bash
# Swagger UI
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/openapi.yaml \
  -v $(pwd):/usr/share/nginx/html \
  swaggerapi/swagger-ui

# Redoc
docker run -p 8080:80 \
  -e SPEC_URL=openapi.yaml \
  -v $(pwd):/usr/share/nginx/html \
  redocly/redoc
```

## Best Practices

- Use semantic versioning
- Include examples in schemas
- Provide clear descriptions
- Use components for reusability
- Define proper error responses
- Include security schemes
- Add operation IDs
- Tag operations logically
- Validate specifications
- Version your APIs

## Reference Documentation

Detailed material lives alongside this skill and is read on demand:

- [Basic OpenAPI Specification](references/BASIC_OPENAPI_SPECIFICATION.md)

## Resources

- OpenAPI Spec: https://spec.openapis.org/
- Swagger Editor: https://editor.swagger.io/
- OpenAPI Tools: https://openapi.tools/
- Stoplight Studio: https://stoplight.io/studio

© personamanagmentlayer · Apache-2.0 · personamanagmentlayer/pcl

Similar skills

All skills for Backend and APIs →

From the same set104

The whole set →
hospitality-expert hospitality-expert hands your agent a hotel-operations vocabulary: property management, reservations, room pricing and guest requests. CX Codex +1 298installs blockchain-expert The blockchain-expert skill guides blockchain, Web3, Solidity, smart contract, and DeFi work. Use it when an agent needs domain context for design, review, or implementation. CX Codex +1 296installs farming-expert farming-expert gives your agent agronomy context: rotation planning, soil sensor readings, NDVI checks and yield estimates, with Python samples. CX Codex +1 283installs energy-expert energy-expert is a Claude Code skill for energy systems, smart grids, and SCADA work. It activates on requests about renewables, power management, or energy analytics. CX Codex +1 282installs git-expert git-expert — a skill that hands the agent ready git recipes: undo a commit, rescue work from main, clean up history. Useful once something has already gone wrong. CX Codex +1 279installs python-expert python-expert configures AI coding agents for modern Python development with type hints, PEP 8 standards, async patterns, and tools like uv, poetry, or ruff. CX Codex +1 277installs redis-expert redis-expert is a Claude Code skill for designing Redis-backed features and reviewing existing setups. It covers caching, pub/sub, data structures, and streams. CX Codex +1 272installs php-expert The php-expert skill guides PHP 8+, Laravel, Composer, and PHPUnit work. Use it for modern PHP implementation, testing, and code review. CX Codex +1 269installs

Project sponsors

Companies that keep this analytics open