How to use the OpenAPI Expert agent skill

What the openapi-expert skill makes the agent do

An agent skill is a folder containing a SKILL.md file with instructions the agent reads when a task matches the skill's description. This one is for OpenAPI and Swagger work. Once it is loaded, the agent structures API contracts with info, servers, paths and components, reuses schemas through $ref, composes schemas with allOf, oneOf and anyOf, sets up security schemes, and applies consistent pagination and error formats.

• Organises the document into info (title, version, contact), servers (base URLs per environment), paths and components.
• Reuses schemas, parameters and responses with $ref instead of duplicating them.
• Composes schemas with allOf (inheritance), oneOf (exactly one match) and anyOf (at least one match).
• Defines security schemes such as Bearer JWT, API key and OAuth2 in components/securitySchemes.
• Uses a standard error object (code, message, details) and a pagination envelope.
• Writes descriptions and examples for paths, parameters, properties and enums.

Install the skill from the ZIP

Download the ZIP for openapi-expert from this page and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of two places, depending on how you want to use it.

For a personal setup available across projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it applies only there.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/openapi-expert/
• Project only: .claude/skills/openapi-expert/ inside your repository
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with a natural request

You do not need a special command. Describe the API work in plain language that mentions OpenAPI, a specification, an API contract, or a Swagger file. The skill's description covers OpenAPI and Swagger design, validation and code generation, so requests in that area are the ones it is meant to handle.

Be specific about the resources and the consumers. The skill is most useful when you give the agent the entities, the endpoints you need and any constraints such as authentication or pagination style.

• Design an OpenAPI 3.1 spec for a booking API with customers, rooms and reservations. Use Bearer JWT auth and cursor pagination.
• Review this openapi.yaml for naming inconsistencies, missing descriptions and versioning gaps.
• Refactor the repeated error responses in this spec into reusable components.
• Model a notification resource that is either an email or a push notification using a discriminator with oneOf.

Examples of what a good result looks like

For a new endpoint, expect the agent to put shared objects under components/schemas, reference them with $ref, and give each path and property a description. For an existing file, expect a review that points to specific paths and suggests changes rather than a full rewrite.

Ask for one area at a time if the spec is large, such as security first, then pagination and errors. This keeps each change easy to review.

• Shared Error schema referenced from every 4xx and 5xx response.
• Paginated list endpoints wrapped in a data and pagination envelope.
• Enum values documented with what each state means, for example PENDING, ACTIVE and SUSPENDED.

Know what the skill does not do

The skill is guidance only. It shapes the specification the agent writes. It does not validate the file, generate server stubs or client SDKs, or run any tool itself. The text mentions openapi-generator and linting tools, and the agent can recommend them, but you run them yourself in your own environment.

The skill declares no required dependencies, does not run scripts, and does not use the network. Its only bundled file is SKILL.md.

• Does not run validators or linters for you.
• Does not run openapi-generator or produce code.
• Does not check your spec against a live API.
• Requires nothing listed beyond the agent that loads it.

Tips for better results

Give the agent your existing spec or a list of resources before asking for changes. Name your naming convention (for example, camelCase or snake_case) so the agent stays consistent with it. Ask it to explain each change if you are learning OpenAPI.

Run your own linter and validator after the agent writes or edits the file, and treat the output as a draft to review.

• State the OpenAPI version you target, 3.0 or 3.1.
• Ask for descriptions and examples explicitly if you need documentation-ready output.
• Keep a single naming convention across all endpoints.