PlugWiki

openapi-spec-generation Skill: Write and Validate OpenAPI 3.1 Specs

Helps your agent create, maintain and validate OpenAPI 3.1 specs, either design-first or generated from existing code.

Installs
16.8K
on skills.sh
Stars
42.1K
on GitHub
Files
2
besides SKILL.md
Updated
Oct 2026
last repo commit

The SKILL.md itself is short: the OpenAPI 3.1 structure, a table comparing design-first, code-first and hybrid, and do and don't lists. The working templates sit in two reference files the agent reads when it needs them.

Those files hold a complete spec template, FastAPI and Express (tsoa) code-first examples, Spectral and Redocly linting setup, and SDK generation with OpenAPI Generator. The agent may install those tools globally with npm, so approve each command.

Good for

  • Backend developers documenting a REST API
  • Teams that want an API contract before writing code
  • Developers generating client SDKs from a spec

Install openapi-spec-generation

Claude Code

  1. 1

    Copy this prompt.

    Install the openapi-spec-generation skill in Claude Code. Run this command:

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

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance.

Sections in SKILL.md

  1. When to Use This Skill
  2. Core Concepts
  3. 1. OpenAPI 3.1 Structure
  4. 2. Design Approaches
  5. Templates and detailed worked examples
  6. Best Practices
  7. Do's
  8. Don'ts

Key facts

Author
wshobson
Installs on skills.sh
16,778 (Nov 2, 2026)
GitHub stars
42,081 (Nov 2, 2026), whole repo
Files
3 files including SKILL.md
Last commit
Oct 30, 2026 (repo)
Part of
The documentation-generation plugin in wshobson/agents
Spec version
OpenAPI 3.1

What it includes

  • Design-first, code-first, hybrid

    A table of when each fits: new APIs, existing APIs, evolving APIs.

    Design approaches

  • A complete OpenAPI 3.1 specification

    A worked User Management API spec in references/details.md: /users list and create, /users/{userId} get, patch and delete, shared schemas (User, create and update requests, a paginated list, Error), reusable parameters and error responses (400, 401, 404, rate limit) and bearerAuth and apiKey security schemes.

    Template 1: full spec

  • Code-first spec from FastAPI and Pydantic

    In references/code-first-and-tooling.md: Pydantic enums and models, endpoints, and a step that exports the generated spec to a file.

    Write · Template 2: FastAPI

  • Code-first spec from TypeScript

    In references/code-first-and-tooling.md: a tsoa controller for users with typed request bodies and @Response decorators for 400, 401, 404 and 409 errors.

    Write · Template 3: Express with tsoa

  • Spectral ruleset and Redocly config

    In references/code-first-and-tooling.md: installs @stoplight/spectral-cli and @redocly/cli with npm install -g, writes .spectral.yaml and redocly.yaml, then runs spectral lint and redocly lint, bundle and preview-docs.

    Runs code · Template 4: Validation and linting

  • OpenAPI Generator for TypeScript, Python and Go

    Installs @openapitools/openapi-generator-cli with npm install -g and generates clients.

    Runs code · SDK generation

From the official docs

Permissions

Low risk

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • The references install global npm packages

    Template 4 and SDK generation run npm install -g for Spectral, Redocly and OpenAPI Generator. Install only what you want. github.com

Questions

What does the openapi-spec-generation skill do?

It helps your agent write OpenAPI 3.1 specs, check them with linters and generate client SDKs. It supports design-first work and generating a spec from FastAPI or Express code.

How do I install it?

Use the install box above. The skill is a SKILL.md plus two reference files, 3 files in all. It does not depend on other skills.

Does it need extra tools?

Only for linting and SDKs. The references install Spectral, Redocly and OpenAPI Generator globally with npm. You can skip those and use the templates alone.

Is it safe?

The guidance is text, but the references include global npm installs and commands that write spec and config files. Approve those commands one at a time.

Design-first or code-first?

The skill's table suggests design-first for new APIs and contracts, code-first for existing APIs and hybrid for evolving APIs.

Does it work in Cursor or Codex?

The wshobson/agents README lists Claude Code, Codex CLI, Cursor, OpenCode, Antigravity CLI, GitHub Copilot and Pi, each with its own install route.

Information

updated Nov 2, 2026

Repository
wshobson/agents
Folder
plugins/documentation-generation/skills/openapi-spec-generation

wshobson/agentsskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3
  1. openapi-spec-generation SKILL.md · github.com
  2. code-first-and-tooling.md · github.com
  3. details.md · github.com

Updated Nov 2, 2026.