OpenAPI Spec Generation
Write, generate, and validate OpenAPI 3.1 API specs from code or design-first contracts
- Repository
- wshobson/agents
- Stars
- 42,095
- Licence
- MIT
- Files
- 3 files
What it does
Once installed, the agent follows structured patterns for writing OpenAPI 3.1 specifications, the standard machine-readable format that describes a web API's endpoints, data shapes, and security. It can create a spec from scratch, generate one from existing code, or check an implementation against a spec, and it applies best practices such as reusing schemas, documenting errors, and defining security schemes. Detailed templates and worked examples are loaded from a reference file when needed.
Great for
- Backend developers who need API documentation for an existing REST service
- Teams adopting a design-first workflow to agree on an API contract before coding
- Developers preparing specs that will be used to generate client SDKs
Skip it if
- Non-technical users who only need general documentation, since the output is developer-focused YAML and assumes familiarity with REST APIs
- Projects that do not expose HTTP APIs, since OpenAPI describes REST-style interfaces only
Try asking
- “Generate an OpenAPI 3.1 spec from my Express routes and models”
- “Design an OpenAPI contract for a new orders API before we write any code”
- “Review my existing openapi.yaml for missing error responses and security schemes”
- “Create a starter spec with reusable schemas and examples for our payments endpoints”
Install in 3 steps
- 1
Download the skill
The ZIP contains the 3 original files, the MIT licence and an attribution note.
openapi-spec-generation.zip - 2
Add it to your agent
Claude Code (all projects)
mkdir -p ~/.claude/skills && unzip openapi-spec-generation.zip -d ~/.claude/skills/Claude Code / Agent SDK (this project only)
mkdir -p .claude/skills && unzip openapi-spec-generation.zip -d .claude/skills/Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.
- 3
Ask for the task
No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.
Get better results
- Point the agent at your actual source files or existing spec so it generates from real code rather than guessing endpoints.
- Ask for a validation pass with an OpenAPI linter such as Spectral in your own environment, since this skill itself only provides patterns.
- Review generated examples and security definitions carefully before publishing docs or generating SDKs.
What's inside
- references/code-first-and-tooling.md
- references/details.md
- SKILL.md
Redistributed unmodified from wshobson/agents under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.