How to use the OpenAPI Spec Generation agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file of instructions that an AI agent loads when a task matches the skill's description. This skill covers three jobs: creating a spec from scratch, generating a spec from existing code, and checking an implementation against a spec.

It also applies best practices from its guidance, such as reusing schemas with $ref, documenting possible error codes, defining every security scheme, and using server variables instead of hardcoded URLs. Detailed templates and worked examples are stored in a separate reference file and loaded only when needed.

• Design-first: write the spec before the code, to agree on a contract.
• Code-first: generate a spec from an existing API, with examples for Python/FastAPI and TypeScript/tsoa.
• Validation: check an implementation against a spec and use linting and SDK generation patterns.

Install the openapi-spec-generation skill

Download the skill ZIP from this page and unzip it. The skill folder contains SKILL.md and a references folder with two files. Put the folder in one of two places depending on how you want to use it.

For all your projects, unzip it into your personal skills folder at ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder so it applies only there and can be shared with your team through the repository.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Ask for a spec with a natural request

You do not need a special command. The skill's description tells the agent when to use it, so plain requests about API documentation, contracts or SDKs should be enough. Name your framework or language and point the agent at your code or your intended endpoints.

Be specific about the goal. A request to create a spec for an existing service produces a code-first result, while a request to design an API before building it produces a design-first contract.

• "Generate an OpenAPI 3.1 spec from my FastAPI routes in app/api."
• "Design an OpenAPI 3.1 contract for a todo API before we write any code."
• "Check whether our Express handlers match the openapi.yaml in this repo."
• "Write the security schemes and error responses for this spec."

Choose between design-first and code-first

The skill describes three approaches. Design-first means writing the spec before code and suits new APIs and contracts. Code-first generates the spec from code and suits existing APIs. Hybrid means annotating code and generating the spec, which suits APIs that are still changing.

If your team needs to agree on endpoints before anyone builds them, ask for design-first. If a REST service already exists and lacks documentation, ask for code-first.

Review and use the output

Read the generated YAML against your real behaviour. Check that servers, paths, schemas and security schemes match what your service actually does, because the agent works from the code or description you give it and cannot confirm runtime behaviour on its own.

Ask the agent to apply the skill's do's and don'ts, such as adding examples, documenting errors and avoiding generic descriptions. For SDK generation or linting, the reference material covers those patterns, but the skill itself does not run any tools.

• Confirm every path and response code matches the implementation.
• Confirm each security scheme is defined and referenced.
• Keep the spec in version control next to the code.