New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Openapi Spec Generator

by sickn33 in sickn33/agentic-awesome-skills

Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs.

MITAuto-check passedBackend & APIs

Install Openapi Spec Generator

skills CLI
$ npx skills add sickn33/agentic-awesome-skills --skill openapi-spec-generator -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install sickn33/agentic-awesome-skills openapi-spec-generator --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/sickn33/agentic-awesome-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/openapi-spec-generator .claude/skills/openapi-spec-generator && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
openapi-spec-generator
GitHub stars
47k
Used in
1 other repo
Token cost
~2.6k tokens
SKILL.md length
894 words
Files
1
Skills in repo
1,354
Repo updated
First seen
Licence
MIT

At a glance

Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs.

  • Works in 8 steps: Gather Context → Build the Spec → Schemas and Models → …
  • Tasks that involve OpenAPI specifications
  • SKILL.md covers When to Use, Workflow, Extracting from Code and Reference Files, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Openapi Spec Generator is an agent skill from sickn33/agentic-awesome-skills. Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering OpenAPI specifications. It works with OpenAPI. The repository describes itself as: AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,400+ agentic skills. Includes… The licence is MIT.

When your agent uses it

  • Tasks that involve OpenAPI specifications

Example prompts

  • “/openapi-spec-generator”

Requirements

  • Node.js

Workflow steps

8 steps, taken from the step headings in SKILL.md.

  1. Gather Context
  2. Build the Spec
  3. Schemas and Models
  4. Security Schemes
  5. Parameters
  6. Response Codes
  7. Quality Checklist
  8. Output

What it can do on your machine

Read from SKILL.md and the folder at commit ec02547. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are yaml).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Openapi Spec Generator loads about 2.6k tokens when it runs. Until then it costs about 40 tokens; SKILL.md has 894 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~40
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from sickn33/agentic-awesome-skills at commit ec02547, republished under its MIT licence (© sickn33). 894 words, ~2,584 tokens.

Download SKILL.mdSave it as .claude/skills/openapi-spec-generator/SKILL.md (or your agent's skills folder).
name
openapi-spec-generator
description
Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs.
risk
critical
source
https://github.com/LambdaTest/agent-skills/tree/main/api-skill/openapi-spec-generator
source_repo
LambdaTest/agent-skills
source_type
community
date_added
2026-07-01
license
MIT
license_source
https://github.com/LambdaTest/agent-skills/blob/main/LICENSE

OpenAPI / Swagger Specification Generator

When to Use

Use this skill when you need generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API...

Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs.

Workflow

Step 1 — Gather Context

Before writing any YAML/JSON, ask (or infer from context) the following:

QuestionWhy it matters
OpenAPI 3.x or Swagger 2.0?Different info, servers/host, components/definitions structure
Output format: YAML or JSON?YAML default unless user specifies JSON
What does this API do?Sets info.title, info.description, tags
List of endpoints (or code to extract from)?Core paths object
Authentication type(s)?securitySchemes — see reference
Common data models or entities?components/schemas / definitions
Any existing partial spec to extend?Merge rather than overwrite

If the user provides code (Express routes, FastAPI, Django URLs, Spring controllers, etc.), extract endpoints automatically — do not ask what the user already told you.

Step 2 — Build the Spec

Follow the structure guide for the chosen version. Always produce a complete, valid spec — never leave placeholder comments like # TODO: add schema.

OpenAPI 3.x Skeleton
yaml
openapi: "3.1.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
  contact:
    name: <Team or Author>
    email: <contact@example.com>
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
tags:
  - name: <Tag>
    description: <Tag description>
paths:
  /resource:
    get:
      summary: List resources
      operationId: listResources
      tags: [<Tag>]
      parameters: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceList"
              example:
                items: []
                total: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - BearerAuth: []
components:
  schemas: {}
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes: {}
Swagger 2.0 Skeleton
yaml
swagger: "2.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
host: api.example.com
basePath: /v1
schemes: [https]
consumes: [application/json]
produces: [application/json]
tags: []
paths: {}
definitions: {}
securityDefinitions: {}
Step 3 — Schemas and Models
  • Always use $ref for any schema used in more than one place.
  • Include example or examples on every schema and response body.
  • Mark required fields with the required array.
  • Use nullable: true (OAS 3.0) or x-nullable: true (Swagger 2.0) for optional nullable fields.
  • Prefer format keywords: int32, int64, float, date, date-time, uuid, email, uri, byte, binary.

Common schema patterns:

yaml
# Pagination wrapper
PagedResult:
  type: object
  required: [items, total, page, pageSize]
  properties:
    items:
      type: array
      items:
        $ref: "#/components/schemas/Resource"
    total:
      type: integer
      format: int64
      example: 100
    page:
      type: integer
      format: int32
      example: 1
    pageSize:
      type: integer
      format: int32
      example: 20

# Standard error
Error:
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      example: RESOURCE_NOT_FOUND
    message:
      type: string
      example: The requested resource was not found.
    details:
      type: object
      additionalProperties: true

# Timestamps mixin (use allOf)
Timestamps:
  type: object
  properties:
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time
Step 4 — Security Schemes

Read reference/security-schemes.md for detailed patterns. Quick reference:

SchemeOAS 3.x typeNotes
Bearer JWThttp, scheme bearerMost common for REST APIs
API Key (header)apiKey, in headere.g. X-API-Key
API Key (query)apiKey, in queryAvoid — leaks in logs
OAuth 2oauth2Use flows to define grant types
Basic Authhttp, scheme basicOnly over HTTPS
OpenID ConnectopenIdConnectProvide openIdConnectUrl

Apply security globally at the root and override per-operation only where it differs (e.g., public endpoints use security: []).

Step 5 — Parameters

Path parameters — always required: true:

yaml
parameters:
  - name: userId
    in: path
    required: true
    schema:
      type: string
      format: uuid
    example: 123e4567-e89b-12d3-a456-426614174000

Query parameters — document defaults and enums:

yaml
  - name: status
    in: query
    schema:
      type: string
      enum: [active, inactive, pending]
      default: active

Headers — include X-Request-ID, correlation IDs, etc. as common parameters defined under components/parameters.

Step 6 — Response Codes

Always include at minimum:

CodeWhen
200Successful GET, PUT, PATCH
201Successful POST that creates a resource
204Successful DELETE (no body)
400Validation / bad request
401Missing or invalid auth
403Authenticated but not authorized
404Resource not found
409Conflict (duplicate, state mismatch)
422Unprocessable entity (semantic errors)
429Rate limited
500Internal server error

Use $ref to components/responses for 401, 403, 404, 429, 500 to avoid repetition.

Step 7 — Quality Checklist

Before delivering the spec, verify:

  • openapi or swagger version field present
  • Every path has at least one operation
  • Every operation has operationId (camelCase, unique)
  • Every operation has at least one 200/201/204 response
  • 4xx and 5xx responses defined for all operations
  • All $ref targets exist in components/ or definitions/
  • Required fields listed in required array for all request/response bodies
  • Security schemes defined AND applied
  • At least one example per schema or response body
  • Tags defined at root level to match operation tags
  • No orphaned schemas (everything in components/schemas is referenced)
Show full SKILL.md (346 more words)Show less
Step 8 — Output
  1. Emit the complete YAML (or JSON) spec in a code block labeled yaml or json.
  2. After the spec, provide a brief summary table of endpoints generated.
  3. Offer to:
    • Export as .yaml / .json file
    • Validate against Spectral or swagger-parser
    • Generate mock server config (Prism)
    • Generate client SDK stubs (language of choice)

Extracting from Code

When the user provides source code, extract:

Express / Koa / Fastify (Node.js)

  • Look for .get(), .post(), .put(), .patch(), .delete() calls
  • Route params :param → path parameter {param}
  • Middleware like authenticate → note security requirement
  • req.body, req.query, req.params usage → infer request schema

FastAPI / Flask (Python)

  • Decorators: @app.get(), @router.post(), etc.
  • Pydantic models → translate directly to JSON Schema
  • Query(), Path(), Body() → map to parameter location

Spring Boot (Java)

  • @GetMapping, @PostMapping, etc.
  • @PathVariable, @RequestParam, @RequestBody
  • DTO classes → schemas

Django REST Framework

  • ViewSet and Router → CRUD endpoints
  • Serializer fields → schema properties

Rails

  • routes.rb resource routes → standard REST endpoints
  • Strong params → request body schema

Reference Files

  • reference/security-schemes.md — Detailed security scheme examples for all auth types
  • reference/common-patterns.md — Pagination, HATEOAS, problem+json, webhooks, file upload patterns

Read these when the user asks about a specific pattern or when generating complex auth/pagination setups.

After Completing the OpenAPI/Swagger Specification design

Once the OpenAPI/Swagger Specification output is delivered, ask the user:

"Would you like me to generate API test cases for this design? (yes/no)"

If the user says yes:

  • Check if the API Test Case Generator skill is available in the installed skills list
  • If the skill is available:
    • Read and follow the instructions in the API Test Case Generator skill
    • Use the specification output above as the input
  • If the skill is NOT available:
    • Inform the user: "It looks like the API Documentation skill isn't installed. You can install it and re-run.

If the user says no:

  • End the task here

Limitations

  • Use this skill only when the task clearly matches its upstream source and local project context.
  • Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
  • Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

© sickn33, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/openapi-spec-generator of sickn33/agentic-awesome-skills.

Open the folder on GitHubat commit ec02547

Used in 1 other repository

We found 5 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in sickn33/agentic-awesome-skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Openapi Spec Generator next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Openapi Spec Generator compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Openapi Spec Generator this skillsickn33/agentic-awesome-skills47k1 repos~2.6kAutomated safety check: PassMIT
ToolJet Marketplace Plugin BuilderToolJet/ToolJet41k—~2.1kAutomated safety check: PassAGPL-3.0
Step Partsearthtojake/text-to-cad18k1 repos~1.5kAutomated safety check: PassMIT
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
OpenAPI to MCP Servermcp-use/mcp-use11k—~5.2kAutomated safety check: PassApache-2.0
Use Yaakmountain-loop/yaak19k—~1.9kAutomated safety check: PassMIT

Similar skills

  • ToolJet Marketplace Plugin Builder

    ToolJet/ToolJet

    Turns an API description, such as an OpenAPI file or a Postman collection, into a connector plugin for ToolJet's marketplace and checks it with the repo's validator.

    41k GitHub stars~2.1k tokensUpdated today
    Backend & APIsAuto-check passed

  • Step Parts

    earthtojake/text-to-cad

    Find, evaluate, and download common purchasable CAD parts from step.parts, including named off-the-shelf actuators, servos, motors, electronics boards, connectors, screws, bolts, nuts, washers…

    18k GitHub starsUsed in 1 repo~1.5k tokens
    Backend & APIsAuto-check passed

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed

  • OpenAPI to MCP Server

    mcp-use/mcp-use

    Turns an OpenAPI or Swagger spec into an MCP server with the mcp-use TypeScript SDK, mapping each operation to a tool, wiring auth, testing and deploying.

    11k GitHub stars~5.2k tokensUpdated today
    Backend & APIsAuto-check passed

  • Use Yaak

    mountain-loop/yaak

    A skill your agent uses when the user mentions Yaak, a Yaak workspace, or the yaak command, or asks to call, hit, or smoke test HTTP/REST endpoints, save or organize API requests for reuse or manual…

    19k GitHub stars~1.9k tokensUpdated yesterday
    Backend & APIsAuto-check passed

  • Old Coder API Design

    AmazingAng/old-coder

    Reviews or designs an HTTP/JSON API's endpoints, auth, pagination, versioning and deprecations, guarding against inventing a bespoke interface or silently breaking consumers.

    749 GitHub starsUsed in 1 repo~3.4k tokens
    Backend & APIsAuto-check passed

More from sickn33/agentic-awesome-skills

All 1,354 skills in this repo

  • Liuguang Banlan UI

    sickn33/agentic-awesome-skills

    Implements an interface in one of two named color modes, iridescent white or colorful black, from a parameterized starter that reports measured color intensity.

    47k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed

  • User Thoughts Memory

    sickn33/agentic-awesome-skills

    Saves a user's project decisions, rules and preferences into a project-local mdbase so later sessions and other agents can recover the intent.

    47k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed

  • Using LWC Memory and Graphs

    sickn33/agentic-awesome-skills

    Keeps project decisions, research and verified results available across coding-agent sessions through LWC memory, a document Wiki graph and a CodeGraph code index.

    47k GitHub starsUsed in 1 repo~2k tokens
    Auto-check passed

  • Find Complementary Founders

    sickn33/agentic-awesome-skills

    Guides an agent through assessing its own owner for cofounder fit, publishing an approved profile, and ranking complementary profiles other agents published for their owners.

    47k GitHub starsUsed in 1 repo~4.8k tokens
    Auto-check passed

  • Cline Pilot

    sickn33/agentic-awesome-skills

    Acts as a proxy for the Cline CLI, dispatching coding tasks one at a time, monitoring runs by hard evidence, relaying decisions to you and learning per-project preferences.

    47k GitHub starsUsed in 1 repo~4.6k tokens
    Auto-check passed

  • Content Creator

    sickn33/agentic-awesome-skills

    Drafts and reviews audience-specific content from supplied brand examples, with local scripts for brand voice and SEO diagnostics, channel templates and a content calendar.

    47k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed

Works with

Categories

Questions about Openapi Spec Generator

What does Openapi Spec Generator do?

Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Openapi Spec Generator is an agent skill from sickn33/agentic-awesome-skills.0 specifications from natural language descriptions, code, or partial specs.

When should I use Openapi Spec Generator?

Openapi Spec Generator fits situations like: tasks that involve OpenAPI specifications.

How do I install Openapi Spec Generator in Claude Code?

Run `npx skills add sickn33/agentic-awesome-skills --skill openapi-spec-generator -a claude-code`. Or copy the skill folder (skills/openapi-spec-generator in sickn33/agentic-awesome-skills) into .claude/skills/openapi-spec-generator in your project. Claude Code loads it when a task matches its description.

How do I install Openapi Spec Generator in Codex?

Run `npx skills add sickn33/agentic-awesome-skills --skill openapi-spec-generator -a codex`. Or copy the skill folder (skills/openapi-spec-generator in sickn33/agentic-awesome-skills) into .agents/skills/openapi-spec-generator in your project. Codex loads it when a task matches its description.

Can I use Openapi Spec Generator in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add sickn33/agentic-awesome-skills --skill openapi-spec-generator -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/openapi-spec-generator, .gemini/skills/openapi-spec-generator, .github/skills/openapi-spec-generator and .opencode/skills/openapi-spec-generator in your project.

What does Openapi Spec Generator need to run?

SKILL.md names no scripts, command-line tools or credentials: Openapi Spec Generator is instructions for the agent only. Our summary lists: Node.js.

Does Openapi Spec Generator access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Openapi Spec Generator safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Openapi Spec Generator use?

Openapi Spec Generator is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Openapi Spec Generator use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Openapi Spec Generator?

Skills that share tags, products or a category with Openapi Spec Generator: ToolJet Marketplace Plugin Builder (ToolJet/ToolJet, 41k stars), Step Parts (earthtojake/text-to-cad, 18k stars), API Designer (Jeffallan/claude-skills, 12k stars) and OpenAPI to MCP Server (mcp-use/mcp-use, 11k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Openapi Spec Generator?

sickn33 (a GitHub user) maintains it in sickn33/agentic-awesome-skills, which has 47,343 GitHub stars. The repository holds 1,354 skills in this directory. The repository was last updated on October 7, 2026.

Source: sickn33/agentic-awesome-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.