Best for
- Creating API documentation from scratch
- Generating OpenAPI specs from existing code
- Designing API contracts (design-first approach)
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
- 38,313
- Declared platforms
- 0
- Static risk flags
- 2
- Last source update
- 2026-07-22
- Source checked
- 2026-07-28
Decision brief
What it does—and where it fits
Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.
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
| Platform | Status | Evidence | What to check |
|---|---|---|---|
| Codex | Not declared | No explicit evidence | Portability before use |
| Claude Code | Not declared | No explicit evidence | Portability before use |
| Cursor | Not declared | No explicit evidence | Portability before use |
| Gemini CLI | Not declared | No explicit evidence | Portability before use |
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/c4b82b0ad771190355eb8e204b1329732a18449a/plugins/documentation-generation/skills/openapi-spec-generation/SKILL.md at commit c4b82b0ad771190355eb8e204b1329732a18449a. 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
- 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) - 02
Core Concepts
Review the “Core Concepts” section in the pinned source before continuing.
Review and apply the “Core Concepts” source section. - 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. - 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
The documentation includes network, browsing, or remote request actions.
url: https://api.example.com/v1Reads files
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
| Signal | Value | Evidence type | Meaning |
|---|---|---|---|
| Quality score | 75/100 | Computed | Documentation, specificity, maintenance, and trust rules |
| Repository stars | 38,313 | Source | Repository attention, not individual Skill quality |
| Compatibility | 0 platforms | Source | Declared in the catalog source record |
| Usage guide | automated source guide | Editorial | Generated 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
- c4b82b0ad771190355eb8e204b1329732a18449a
- License
- MIT
- Collected
- 2026-07-28
- 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
| Approach | Description | Best For |
|---|---|---|
| Design-First | Write spec before code | New APIs, contracts |
| Code-First | Generate spec from code | Existing APIs |
| Hybrid | Annotate code, generate spec | Evolving 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
Alternatives
Compare before choosing
Computed 9731,966
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.
Computed 9438,313
wshobson/agents
architecture-decision-records
Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
Computed 9438,313
wshobson/agents
brand-landingpage
Brand-first landing page designer — runs a brand-identity interview (colors, typography, shape language), then generates and iterates on a polished landing page via Stitch with deployment-ready HTML. Use when the user asks to create, design, or build a landing page, homepage, or marketing page and has no established visual direction. Skip when they have a design mockup, need a dashboard or app UI, are working at component level, building a multi-page app, or restyling with known design tokens —
Computed 9037,126
github/awesome-copilot
screen-recording
Create annotated animated GIF demos and screen recordings for pull requests and documentation. Covers frame capture, timing, imageio-based GIF creation, and per-frame annotation workflows.