Design API Spec

Generate an OpenAPI 3.1.0 specification from API design stories, a domain model, API standards, and an OpenAPI best practices file. Then lint it with RateMyOpenAPI and fix issues. This is part of Emmanuel Paraskakis's method for designing APIs with LLMs. Stories can come from the companion design-api-stories skill or be written by hand — either way, this skill takes stories + domain + standards + OpenAPI best practices and produces a validated spec.

When to Use

Use when the user says /design-api-spec or asks to generate an OpenAPI spec from stories.

Optional Dependencies

The core skill (spec generation) works with no extra tools. For the full experience:

• RateMyOpenAPI API key — enables automated linting and scoring. Free signup at api.ratemyopenapi.com/docs. Set as RMOA_API_KEY env var.
• Node.js — enables local Swagger UI preview via npx http-server.
• curl + python3 — used for the RMOA API call. Almost always pre-installed.

Without these, the skill still generates a complete OpenAPI spec — it just skips linting and local preview.

Inputs