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
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/openapi-expert/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openapi-expert/
1Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a codex2Manually: put the files in place
.agents/skills/openapi-expert/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a cursor2Manually: put the files in place
.cursor/skills/openapi-expert/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install personamanagmentlayer/pcl stdlib/api/openapi-expert2Manually: put the files in place
.github/skills/openapi-expert/SKILL.md1Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a gemini-cli2Platform CLI
gemini skills install https://github.com/personamanagmentlayer/pcl --path stdlib/api/openapi-expertManually: put the files in place
.devin/skills/openapi-expert/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -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-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