#601

Global Rank · of 601 Skills

openapi AI Agent Skill

View Source: oakoss/agent-skills

Safe

Installation

npx skills add oakoss/agent-skills --skill openapi

54

Installs

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

Installs

Installs 54
Global Rank #601 of 601

Security Audit

ath Safe
socket Safe
Alerts: 0 Score: 90
snyk Low
EU EU-Hosted Inference API

Power your AI Agents with the best open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

GLM

GLM 5

$1.00 / $3.20

per M tokens

Kimi

Kimi K2.5

$0.60 / $2.80

per M tokens

MiniMax

MiniMax M2.5

$0.30 / $1.20

per M tokens

Qwen

Qwen3.5 122B

$0.40 / $3.00

per M tokens

How to use this skill

1

Install openapi by running npx skills add oakoss/agent-skills --skill openapi in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.

2

No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.

3

The skill enhances your agent's understanding of openapi, helping it follow established patterns, avoid common mistakes, and produce production-ready output.

What you get

Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.

Compatibility

This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.

EU Made in Europe

Chat with 100+ AI Models in one App.

Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.

Start for free View pricing
Customer Support