openapi · oakoss — скилл для Claude Code: что делает и как установить
Настраивает агента на проектирование спецификаций OpenAPI 3.1 и генерацию TypeScript-клиентов. Помогает писать схемы контрактов и документацию для REST API.
MIT 197 установок ★ 29 обновлён 2026-08-17
npx skills add oakoss/agent-skills --skill openapi -a claude-codeЧто делает openapi
Скилл обучает агента правилам спецификации OpenAPI 3.1, которая полностью совместима с JSON Schema Draft 2020-12. Он подсказывает структуру корневого документа, синтаксис путей вроде /resources/{id}, вынос повторяющихся моделей в components/schemas и связывание через $ref. Для полиморфизма агент применяет oneOf и поле discriminator.
В сборках скилл ориентируется на кодогенерацию через openapi-typescript и типизированный клиент openapi-fetch. Здесь действует строгое ограничение стандарта: синтаксис nullable: true из OpenAPI 3.0 удалён. Вместо него агент обязан задавать массив типов вроде type: ["string", "null"].
Для GraphQL или gRPC скилл бесполезен: он рассчитан только на протоколы HTTP REST. При сложных проверках типов в коде агент перенаправляет задачу в скилл typescript-patterns.
Какие задачи решает
- спроектировать спецификацию REST API по стандарту OpenAPI 3.1
- настроить генерацию TypeScript-типов через openapi-typescript
- вынести повторяющиеся структуры данных в components/schemas
- исправить ошибки валидации параметров путей и operationId
Примеры запросов агенту
- Создай спецификацию OpenAPI 3.1 для маршрута
/users/{id}с типами ответов и кодами ошибок - Сгенерируй TypeScript-типы из файла
openapi.yamlс помощью openapi-typescript - Проверь схему API на ошибки совместимости со спецификацией OpenAPI 3.1
Как установить openapi
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a claude-code2Вручную: положить файлы
~/.claude/skills/openapi/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/openapi/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a codex2Вручную: положить файлы
.agents/skills/openapi/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a cursor2Вручную: положить файлы
.cursor/skills/openapi/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/openapi2Вручную: положить файлы
.github/skills/openapi/SKILL.md1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a gemini-cli2Командой платформы
gemini skills install https://github.com/oakoss/agent-skills --path skills/openapiВручную: положить файлы
.devin/skills/openapi/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill openapi -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об openapi
Как установить openapi в Claude Code?
Выполните команду npx skills add oakoss/agent-skills --skill openapi -a claude-code. Файл скилла запишется по пути ~/.claude/skills/openapi/SKILL.md.
Что делает скилл openapi?
Он даёт агенту инструкции по созданию спецификаций REST API версии 3.1 и генерации типизированных клиентов. Агент опирается на синтаксис JSON Schema 2020-12 и корректно связывает компоненты через $ref.
Чем синтаксис типов OpenAPI 3.1 отличается от версии 3.0?
В версии 3.1 убрали параметр nullable: true. Теперь nullable-типы объявляются списком type: ["string", "null"], а параметр exclusiveMinimum задаётся числом вместо булева флага.
Исходный текст
SKILL.md · MIT
---
name: openapi
description: 'OpenAPI 3.1 specification, schema design, and code generation. Use when designing REST APIs, generating TypeScript clients, or creating API documentation. Use for openapi, swagger, api-spec, schema, code-generation, api-docs, openapi-typescript, zod-openapi.'
license: MIT
metadata:
author: oakoss
version: '1.1'
source: 'https://spec.openapis.org/oas/v3.1.0'
user-invocable: false
---
# OpenAPI
## Overview
OpenAPI Specification (OAS) 3.1 is the industry standard for describing HTTP APIs. It defines a machine-readable contract covering endpoints, request/response schemas, authentication, and error formats. OpenAPI 3.1 is a strict superset of JSON Schema Draft 2020-12, enabling full JSON Schema compatibility for data validation and type generation.
**When to use:** Designing REST APIs, generating typed clients (TypeScript, Python, Go), producing interactive documentation, validating request/response payloads, contract-first API development, API gateway configuration.
**When NOT to use:** GraphQL APIs (use the GraphQL schema), gRPC services (use Protocol Buffers), WebSocket-only protocols, internal function calls that never cross a network boundary.
## Quick Reference
| Pattern | Element | Key Points |
| --------------- | ------------------------------------------------------- | -------------------------------------------------- |
| Document root | `openapi`, `info`, `paths` | `openapi: '3.1.0'` required at top level |
| Path item | `/resources/{id}` | Curly braces for path parameters |
| Operation | `get`, `post`, `put`, `delete`, `patch` | Each operation needs `operationId` and `responses` |
| Parameters | `in: path\|query\|header\|cookie` | Path params are always `required: true` |
| Request body | `requestBody.content` | Keyed by media type (`application/json`) |
| Response | `responses.200.content` | At least one response required per operation |
| Component ref | `$ref: '#/components/schemas/Name'` | Reuse schemas, parameters, responses |
| Schema types | `type: string\|number\|integer\|boolean\|array\|object` | Arrays support `type: ["string", "null"]` in 3.1 |
| Composition | `oneOf`, `anyOf`, `allOf` | Model polymorphism and intersection types |
| Discriminator | `discriminator.propertyName` | Hint for code generators with `oneOf`/`anyOf` |
| Security | `securitySchemes` + top-level `security` | Bearer, API key, OAuth2, OpenID Connect |
| Tags | `tags` on operations | Group operations for documentation |
| Type generation | `openapi-typescript` | Zero-runtime TypeScript types from spec |
| Typed fetch | `openapi-fetch` | Type-safe HTTP client using generated types |
| React Query | `openapi-react-query` | Type-safe React Query hooks from spec |
| Schema-first | `zod-openapi` | Generate OpenAPI documents from Zod schemas |
## Common Mistakes
| Mistake | Correct Pattern |
| ------------------------------------------ | ------------------------------------------------------------------------------ |
| Using `nullable: true` in 3.1 | Use `type: ["string", "null"]` (3.0 syntax removed) |
| Missing `operationId` on operations | Always set unique `operationId` for code generation |
| Path parameter not in `required` | Path parameters are always required (`required: true`) |
| Inline schemas everywhere | Extract to `components/schemas` and use `$ref` |
| `allOf` with conflicting `required` fields | Merge `required` arrays; `allOf` unions them |
| Discriminator without shared property | All schemas in `oneOf`/`anyOf` must include the discriminator property |
| Empty `description` on responses | Every response needs a meaningful `description` |
| Using `type: object` without `properties` | Always define `properties` or use `additionalProperties` |
| Circular `$ref` chains | Break cycles with lazy resolution or restructure schemas |
| Mixing 3.0 and 3.1 syntax | Choose one version; 3.1 drops `nullable`, changes `exclusiveMinimum` to number |
## Delegation
- **API design review**: Use `Task` agent to audit spec completeness and consistency
- **Type generation**: Use `Explore` agent to find project-specific OpenAPI tooling config
- **Code review**: Delegate to `code-reviewer` agent for generated client usage patterns
> If the `typescript-patterns` skill is available, delegate advanced TypeScript typing questions to it.
## References
- [Schema design: paths, operations, parameters, components, and $ref](references/schema-design.md)
- [Data types: formats, composition, discriminators, and nullable](references/data-types.md)
- [Code generation: openapi-typescript, openapi-fetch, openapi-react-query, and Zod OpenAPI](references/code-generation.md)
- [Documentation: Swagger UI, Redoc, and API docs best practices](references/documentation.md)
© oakoss · MIT · oakoss/agent-skills
Похожие скиллы
Все скиллы по теме «Бэкенд и API» →Сначала — openapi от других авторов.