openapi-expert — скилл для Claude Code: что делает и как установить
Скилл openapi-expert проектирует спецификации OpenAPI 3.0 и 3.1, настраивает полиморфизм схем и генерирует код клиентов или серверов.
Apache-2.0 282 установок ★ 45 обновлён 2026-10-12
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-codeЧто делает openapi-expert
Скилл помогает составлять контракты API в форматах YAML и JSON. Он ориентируется на версии OpenAPI 3.0 и 3.1, подсказывает синтаксис вебхуков и описывает полиморфные модели данных через oneOf, anyOf, allOf и discriminator.
В инструкциях заложены готовые сценарии работы со сторонними утилитами. Агент умеет вызывать кодогенератор @openapitools/openapi-generator-cli для сборки клиентов на TypeScript или серверов на Python и Java, проверять контракты линтером Spectral и поднимать контейнеры Swagger UI или Redoc.
Для автоматического запуска линтера или кодогенерации в терминале понадобятся глобально установленные пакеты Node.js либо Docker.
Какие задачи решает
- описать вебхуки и контракты эндпоинтов по стандарту OpenAPI 3.1
- собрать клиентскую библиотеку на TypeScript через openapi-generator-cli
- проверить готовый YAML-контракт линтером Spectral
- сконфигурировать полиморфные схемы с селектором discriminator
Примеры запросов агенту
- Опиши схему вебхука postCreated в формате OpenAPI 3.1 с телом Post
- Сгенерируй TypeScript-клиент по файлу openapi.yaml через openapi-generator-cli
- Настрой файл .spectral.yaml для проверки operationId и тегов в спецификации
Как установить openapi-expert
1Через Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-code2Вручную: положить файлы
~/.claude/skills/openapi-expert/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/openapi-expert/
1Через Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a codex2Вручную: положить файлы
.agents/skills/openapi-expert/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a cursor2Вручную: положить файлы
.cursor/skills/openapi-expert/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install personamanagmentlayer/pcl stdlib/api/openapi-expert2Вручную: положить файлы
.github/skills/openapi-expert/SKILL.md1Через Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a gemini-cli2Командой платформы
gemini skills install https://github.com/personamanagmentlayer/pcl --path stdlib/api/openapi-expertВручную: положить файлы
.devin/skills/openapi-expert/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill openapi-expert -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об openapi-expert
Как установить openapi-expert в Claude Code?
Выполните в терминале команду npx skills add personamanagmentlayer/pcl --skill openapi-expert -a claude-code. Файл навыка сохранится по пути ~/.claude/skills/openapi-expert/SKILL.md.
Что делает openapi-expert?
Он задаёт модели контекст по правилам OpenAPI 3.0 и 3.1, позволяя проектировать контракты REST API, генерировать клиенты и настраивать валидацию.
Какие внешние инструменты использует этот скилл?
Инструкции ориентированы на @openapitools/openapi-generator-cli для кодогенерации, Spectral для статического анализа спецификаций и образы Swagger UI или Redoc в Docker.
Исходный текст
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