К основному содержанию
скилл CX Codex

openapi · oakoss — скилл для Claude Code: что делает и как установить

Настраивает агента на проектирование спецификаций OpenAPI 3.1 и генерацию TypeScript-клиентов. Помогает писать схемы контрактов и документацию для REST API.

MIT 197 установок ★ 29 обновлён 2026-08-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add oakoss/agent-skills --skill openapi -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/openapi/

По шагам, с командами для каждой платформы: Как установить скилл в 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 от других авторов.

openapi codewithmukesh Настраивает встроенную генерацию спецификаций OpenAPI в .NET 10 без Swashbuckle. Помогает агенту писать трансформеры, метаданные и схемы безопасности. CX Codex +1 4 000установок openapi itechmeat Скилл подсказывает ИИ-агенту структуру документов OpenAPI 3.x: обязательные поля, операции, схемы, параметры и безопасность. CX Codex +1 125установок openapi finom Скилл объясняет, как Vovk.ts собирает спецификацию OpenAPI из процедур и схем валидации. Пригодится, чтобы описать API и показать его документацию через Scalar. CX Codex +1 ★ 57звёзд репо openapi-spec-writer curiositech Скилл openapi-spec-writer проектирует спецификации OpenAPI 3.0 и 3.1 для REST API. Помогает составить схемы данных и настроить документацию ещё до написания серверного кода. CX Codex +1 175установок spring-boot-openapi-documentation giuseppe-trisciuoglio Скилл spring-boot-openapi-documentation помогает агенту настроить SpringDoc OpenAPI 3.0 и Swagger UI в проекте на Spring Boot 3.x и разметить эндпоинты аннотациями. CX Codex +1 4 200установок openapi-expert personamanagmentlayer Скилл openapi-expert проектирует спецификации OpenAPI 3.0 и 3.1, настраивает полиморфизм схем и генерирует код клиентов или серверов. CX Codex +1 282установок go-openapi eduardo-sl Скилл go-openapi настраивает подход spec-first для REST API на Go: генерирует интерфейсы через oapi-codegen, подключает middleware валидации и отслеживает ломающие изменения схемы. CX Codex +1 ★ 90звёзд репо openapi-generator patricio0312rev Скилл openapi-generator для Claude Code, Codex, Cursor и других ИИ-редакторов генерирует спецификации OpenAPI 3.0/3.1 прямо из маршрутов Express, Next.js, Fastify, Hono или NestJS. CX Codex +1 320установок route-to-openapi zebbern Скилл route-to-openapi для Claude Code, сканирует маршруты в коде и собирает спецификацию OpenAPI 3.0.3. Автоматизирует генерацию документации API из определений эндпоинтов. CX Codex +1 ★ 4 719звёзд репо

Из того же набора106

Весь набор →
database-security Скилл database-security проверяет доступ к данным в Supabase, Postgres и Convex: покрытие RLS, дыры в политиках, аудит-логи. Пригодится перед релизом или при разборе инцидента. CX Codex +1 208установок typescript-patterns Скилл typescript-patterns учит ИИ-агента сложным приёмам TypeScript в строгом режиме. Он помогает избежать сбоев во время выполнения за счёт проверок на этапе сборки. CX Codex +1 202установок react-patterns Скилл react-patterns по React 19+: паттерны хуков, выбор управления состоянием, загрузка данных через use() и борьба с лишними ре-рендерами. CX Codex +1 201установок ci-cd-architecture Скилл ci-cd-architecture помогает спроектировать CI/CD-пайплайн, выбрать платформу деплоя и настроить безопасность GitHub Actions. Пригодится при запуске и развитии проекта. CX Codex +1 199установок css-animation-patterns Скилл css-animation-patterns для Claude Code помогает создавать CSS-анимации без перерисовки макета. Описывает аппаратно ускоренные свойства, переходы и новые API движения. CX Codex +1 196установок pnpm-workspace Скилл pnpm-workspace настраивает монорепозитории на базе pnpm и каталоги версий. Помогает агенту связывать локальные пакеты через протокол workspace:. CX Codex +1 195установок icon-design Скилл icon-design помогает выбрать подходящие по смыслу иконки из Lucide, Heroicons или Phosphor и настроить чистый импорт без поломки tree-shaking. CX Codex +1 187установок pdf-tools Скилл pdf-tools для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI, который покрывает весь цикл работы с PDF: извлечение текста и таблиц, генерацию, изменение и заполнение форм. CX Codex +1 186установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой