openapi-spec-generation

Overview of openapi-spec-generation skill

What the openapi-spec-generation skill does

The openapi-spec-generation skill helps an agent create or improve OpenAPI 3.1 API specifications using proven patterns instead of ad hoc prompting. It is aimed at teams that need a usable contract for documentation, client SDK generation, validation, and API governance, not just a rough YAML draft.

Who should use it

This skill is a strong fit for:

• backend teams documenting an existing REST API
• platform teams standardizing contracts across services
• developers moving from code-first frameworks to a cleaner spec
• teams preparing for SDK generation, mock servers, or contract checks

It is less about “what is OpenAPI?” and more about “how do I get a complete, credible spec with fewer gaps?”

Real job-to-be-done

Most users do not simply want a file called openapi.yaml. They want a spec that is good enough to:

• describe real request and response shapes
• model authentication, errors, pagination, and common headers
• support tooling downstream
• stay maintainable as the API changes

The openapi-spec-generation skill is useful because it pushes the work toward OpenAPI 3.1 structure, design approach selection, and concrete templates rather than generic API prose.

What differentiates this skill

Compared with a normal “write me an OpenAPI spec” prompt, this skill gives agents:

• explicit OpenAPI 3.1 framing
• guidance for design-first, code-first, and hybrid workflows
• reusable templates for full specifications
• code-first examples in the included references/code-first-and-tooling.md

That makes it especially relevant for openapi-spec-generation for API Development where teams must bridge implementation details and contract quality.

What to check before installing

Before adopting the openapi-spec-generation skill, decide whether your main need is:

• drafting a new contract from product requirements
• extracting a contract from existing code
• tightening an already existing spec

If your API is highly RPC-style, event-driven, or not REST-oriented, this skill may need adaptation rather than direct use.

How to Use openapi-spec-generation skill

openapi-spec-generation install context

Install the parent skill collection, then invoke openapi-spec-generation from your agent workflow:

npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation

This skill lives in the wshobson/agents repository under plugins/documentation-generation/skills/openapi-spec-generation.

Read these files first

For fastest understanding, read:

1. plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md
2. plugins/documentation-generation/skills/openapi-spec-generation/references/code-first-and-tooling.md

SKILL.md gives the main scope and templates. The reference file adds practical code-first patterns, especially useful if your source of truth is application code.

Choose the right starting approach

The skill supports three practical entry points:

• Design-first: best for new APIs and contract review before implementation
• Code-first: best when the API already exists in frameworks like FastAPI
• Hybrid: best when code exists but you still want a more curated public contract

This choice affects prompt quality more than most users expect. If you skip it, outputs often become vague or internally inconsistent.

What inputs the skill needs

The openapi-spec-generation usage is strongest when you provide concrete API evidence, such as:

• route list with methods and path params
• example request and response JSON
• auth model
• pagination style
• major error cases
• entity schemas or validation models
• environment/server URLs
• naming conventions and versioning rules

If you only provide “generate a spec for my user API,” expect a template-heavy draft that still needs real contract work.

Turn a rough goal into a strong prompt

Weak prompt:

• “Generate an OpenAPI spec for a user service.”

Stronger prompt:

• “Use the openapi-spec-generation skill to create an OpenAPI 3.1 spec for a REST API with GET /users, POST /users, GET /users/{id}, and PATCH /users/{id}. Auth is bearer token. Users have id, email, name, status, and createdAt. Use cursor pagination on list endpoints, include standard 400/401/404/409 responses, model reusable schemas under components, and produce a clean spec suitable for SDK generation.”

The stronger version gives the skill enough structure to generate a contract instead of a placeholder.

Best workflow for existing APIs

For existing services, a practical openapi-spec-generation guide looks like this:

1. Inventory routes from code or router definitions.
2. Extract request models, response models, enums, and validations.
3. Decide whether generated framework docs are the baseline or just a reference.
4. Ask the skill to normalize everything into OpenAPI 3.1.
5. Review for missing error responses, auth details, examples, and schema reuse.
6. Run your own validation or linting tools afterward.

This works better than asking for a full spec in one pass from partial memory.

Best workflow for new APIs

For new APIs:

1. Define resources and operations first.
2. Decide versioning, auth, and pagination patterns.
3. Ask the skill for a design-first spec with reusable components.
4. Review naming consistency and error model before coding.
5. Use the accepted spec as the contract for implementation.

This is where the skill has high leverage, because contract mistakes are cheaper to fix before code exists.

How to use the code-first reference well

The included references/code-first-and-tooling.md is especially useful if you are working from Python or TypeScript ecosystems. It shows what better source material looks like:

• typed models
• enum usage
• validation metadata
• framework-level descriptions and tags
• server definitions

That matters because code-first OpenAPI generation quality depends heavily on how well your code models the domain.

What good output should include

A solid result from the openapi-spec-generation skill should usually include:

• openapi: 3.1.0
• clear info metadata
• realistic servers
• complete paths
• reusable components.schemas
• security schemes
• common response/error handling
• examples where ambiguity would hurt adoption

If these are missing, the draft is not yet ready for downstream tooling.

Common repository-reading path

If you want to inspect the upstream material before relying on the skill, use this path:

• scan SKILL.md for scope, structure, and templates
• open references/code-first-and-tooling.md for implementation-oriented examples
• compare those examples against your framework and current API maturity

This repo is lightweight, so the value is in prompt scaffolding and examples rather than automation scripts.

Practical tips that improve output quality

• Provide real field names, not placeholders.
• State whether nullability is allowed.
• List error codes you actually use.
• Specify whether IDs are UUIDs, integers, or opaque strings.
• Say if your list endpoints use cursor, page/size, or offset/limit pagination.
• Tell the skill which schemas should be shared across endpoints.

These details reduce cleanup work dramatically.

openapi-spec-generation skill FAQ

Is openapi-spec-generation good for beginners?

Yes, if you already understand your API. The skill helps structure a spec, but it does not replace knowing your endpoints, auth, and data models. Beginners with no API inventory may still struggle to provide enough source input.

Is this better than a normal OpenAPI prompt?

Usually yes. The openapi-spec-generation skill gives a better starting frame than a generic prompt because it centers OpenAPI 3.1, design approach choice, and practical templates. The difference is less about creativity and more about completeness and consistency.

Does it generate specs directly from code?

Not by itself in an automated repo-scanning sense. It provides patterns and examples for code-first generation, especially through the reference file, but you still need to give the agent the relevant code context or extracted endpoint details.

When is this skill a bad fit?

It is a weaker fit when:

• your API is not REST-like
• you need full automatic extraction from a large codebase
• your main problem is runtime testing rather than contract creation
• you need framework-specific tooling setup more than spec authoring guidance

In those cases, dedicated generators or framework-native tooling may be a better primary path.

Can I use it for maintaining an existing spec?

Yes. openapi-spec-generation is useful for tightening incomplete specs, aligning them to OpenAPI 3.1, and adding missing reusable components, responses, and documentation structure.

Is it suitable for SDK generation workflows?

Yes, if you review the result carefully first. SDK generation is sensitive to schema quality, enum modeling, operation IDs, auth definitions, and response consistency. This skill helps draft those pieces, but final validation is still your responsibility.

How to Improve openapi-spec-generation skill

Give the skill contract-grade inputs

The fastest way to improve openapi-spec-generation results is to stop prompting at the feature level and start prompting at the contract level. Include:

• exact endpoints
• required and optional fields
• enum values
• example payloads
• status codes
• authentication rules
• reusable object shapes

This changes the output from “spec-shaped text” into something much closer to production-ready.

Ask for missing sections explicitly

Many first drafts miss operationally important details. Ask the skill to include:

• security schemes
• pagination parameters
• error response schema
• operation IDs
• reusable request bodies
• tags and descriptions
• examples for confusing fields

Explicit asks are worth it because generic spec drafts often under-document these areas.

Prevent schema drift in code-first workflows

If you use openapi-spec-generation for API Development against an existing service, schema drift is the main risk. Reduce it by supplying:

• current model definitions
• validation constraints
• route handlers or controller signatures
• known deviations between implementation and docs

Without this, the skill may produce a cleaner contract than the actual API, which is useful editorially but risky operationally.

Iterate in passes, not one giant request

A better process is:

1. generate the skeleton
2. refine schemas
3. refine auth and errors
4. add examples
5. standardize naming and reuse

This pass-based workflow usually beats a single monolithic prompt, especially for medium-sized APIs.

Watch for common failure modes

Common issues in first outputs:

• generic descriptions with little operational value
• missing error models
• inconsistent naming between paths and schemas
• under-specified request validation
• no clear distinction between create, update, and read models
• examples that do not match schema constraints

These are fixable, but only if you review with real API behavior in mind.

Use the reference file as a prompt ingredient

A simple way to improve the openapi-spec-generation guide in practice is to tell the agent to follow the structure and detail level shown in references/code-first-and-tooling.md, especially for:

• typed schemas
• enum handling
• validation metadata
• server definitions
• model descriptions

That gives the agent a stronger pattern than a plain “make it complete” instruction.

Validate after generation

Even strong drafts should be checked with your normal OpenAPI validators, linters, and downstream generators. The skill helps produce a better first version; it does not replace verification. This is especially important if the output will drive docs portals, code generation, or contract testing.

Improve the skill output with narrower scopes

If your first attempt is messy, narrow the request:

• one resource at a time
• one path group at a time
• one schema family at a time

Then merge the reviewed pieces. For many teams, this is the highest-reliability way to use openapi-spec-generation usage in production work.