Source profileQuality 75/100

wshobson/agents/plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md

openapi-spec-generation

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.

Source repository stars
39,130
Declared platforms
0
Static risk flags
2
Last source update
2026-08-24
Source checked
2026-08-26
DecisionCompatibilityInstallWorkflowPermissionsEvidenceSourceFAQ

Decision brief

What it does: where it fits

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

Best for

  • Creating API documentation from scratch
  • Generating OpenAPI specs from existing code
  • Designing API contracts (design-first approach)

Not for

  • Tasks that require unconfirmed production actions or broad system permissions.
  • Environments where the pinned source and install steps cannot be inspected.

Compatibility matrix

Platform support, with evidence labels

PlatformStatusEvidenceWhat to check
CodexNot declaredNo explicit evidencePortability before use
Claude CodeNot declaredNo explicit evidencePortability before use
CursorNot declaredNo explicit evidencePortability before use
Gemini CLINot declaredNo explicit evidencePortability before use
Open the compatibility checker

Installation

Inspect first. Install second.

The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.

Source-detected install commandSource
npx skills add https://github.com/wshobson/agents --skill "plugins/documentation-generation/skills/openapi-spec-generation"
Safe inspection promptEditorial

Inspect the Agent Skill "openapi-spec-generation" from https://github.com/wshobson/agents/blob/d82998e7df393c671ede2387a8435075f0b633f5/plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md at commit d82998e7df393c671ede2387a8435075f0b633f5. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.

Workflow

What the source asks the agent to do

  1. 01

    When to Use This Skill

    Creating API documentation from scratch

    Creating API documentation from scratchGenerating OpenAPI specs from existing codeDesigning API contracts (design-first approach)
  2. 02

    Core Concepts

    Review the “Core Concepts” section in the pinned source before continuing.

    Review and apply the “Core Concepts” source section.
  3. 03

    1. OpenAPI 3.1 Structure

    Review the “1. OpenAPI 3.1 Structure” section in the pinned source before continuing.

    Review and apply the “1. OpenAPI 3.1 Structure” source section.
  4. 04

    2. Design Approaches

    Review the “2. Design Approaches” section in the pinned source before continuing.

    Review and apply the “2. Design Approaches” source section.

Permission review

Static risk signals and limitations

Network access

medium · line 24

The documentation includes network, browsing, or remote request actions.

url: https://api.example.com/v1

Reads files

low · line 43

The documentation asks the agent to read local files, directories, or repositories.

Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.

Evidence record

Why each signal appears

EvidenceSourceComputedTestedEditorial
SignalValueEvidence typeMeaning
Quality score75/100ComputedDocumentation, specificity, maintenance, and trust rules
Repository stars39,130SourceRepository attention, not individual Skill quality
Compatibility0 platformsSourceDeclared in the catalog source record
Usage guideautomated source guideEditorialGenerated or reviewed according to the visible evidence level

Pinned source

Provenance and original SKILL.md

Repository
wshobson/agents
Skill path
plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md
Commit
d82998e7df393c671ede2387a8435075f0b633f5
License
MIT
Collected
2026-08-26
Default branch
main
View the original SKILL.md

OpenAPI Spec Generation

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

When to Use This Skill

  • Creating API documentation from scratch
  • Generating OpenAPI specs from existing code
  • Designing API contracts (design-first approach)
  • Validating API implementations against specs
  • Generating client SDKs from specs
  • Setting up API documentation portals

Core Concepts

1. OpenAPI 3.1 Structure

openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...

2. Design Approaches

ApproachDescriptionBest For
Design-FirstWrite spec before codeNew APIs, contracts
Code-FirstGenerate spec from codeExisting APIs
HybridAnnotate code, generate specEvolving APIs

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

  • Use $ref - Reuse schemas, parameters, responses
  • Add examples - Real-world values help consumers
  • Document errors - All possible error codes
  • Version your API - In URL or header
  • Use semantic versioning - For spec changes

Don'ts

  • Don't use generic descriptions - Be specific
  • Don't skip security - Define all schemes
  • Don't forget nullable - Be explicit about null
  • Don't mix styles - Consistent naming throughout
  • Don't hardcode URLs - Use server variables

Frequently asked questions

What to verify before installation and use

What does the openapi-spec-generation source document cover?

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

How do I install openapi-spec-generation?

The source record exposes this install command: npx skills add https://github.com/wshobson/agents --skill "plugins/documentation-generation/skills/openapi-spec-generation". Inspect the command and pinned source before running it.

Which permission-related actions were detected?

Static rules flagged network, read-files in the source; the page lists the matching lines and excerpts.

Alternatives

Compare before choosing

Computed 100146

oaustegard/claude-skills

featuring

Generate hierarchical _FEATURES.md files that describe what a codebase DOES from a user/consumer perspective, anchored to source symbols via tree-sitting. Supports large complex codebases through feature-driven decomposition into sub-feature files. Uses a multi-pass synthesis: orientation → detail → overview rewrite. Use when someone says "what does this do", "document features", "feature inventory", "_FEATURES.md", or needs to understand a codebase's purpose before modifying it. Complements tre

2026-08-251 platforms
Computed 9916

NintendaDev/unikit-ai

unikit-docs

Generate and maintain the project's TECHNICAL documentation from its codebase — scans the project structure, tech stack, and module boundaries, then writes a lean README landing page plus detailed topic pages (architecture, modules, setup, build, APIs), only the docs that are relevant. Use whenever the user wants to create, update, or validate documentation of the CODE or the project itself, e.g. "generate documentation", "create docs", "write the README", "update the project docs", "document th

2026-08-190 platforms
Computed 9817

eugenelim/agent-ready-repo

work-loop

Use when implementing or resuming a non-trivial repository change: a feature, behavior-changing fix, refactor, migration, framework or dependency upgrade, schema or API change, performance work, infrastructure or build-system change, reversion, or an existing build spec under `docs/specs/`. Also use for bare continuation commands ('resume', 'continue', 'keep going', 'pick up where I left off', 'let's get going') when conversation or workspace context identifies active build work. Do not use for

2026-08-260 platforms
Computed 9734,478

K-Dense-AI/scientific-agent-skills

esm

Use when working directly with the `esm` Python SDK, ESM3 or ESMC model IDs, Forge/Biohub inference clients, or ESMFold2 folding workflows.

2026-08-240 platforms