Design production-ready REST API specifications

This skill generates complete, production-ready REST API endpoint specifications for any system or domain the user describes. It first asks whether the user wants "Endpoints Only" or a full "Detail Design" (skipping the question if the requirement is already specific enough), then, for a detailed design, lists every endpoint and expands each one into a fixed structure: resource name, method and path, a short description, a headers table (Content-Type, Authorization, X-Api-Key), a realistic request body JSON example, a success response with its HTTP status code, and a relevant subset of error codes (400, 401, 403, 404, 409, 422, 500). It covers all major resources for the described system, infers resources the user doesn't list, includes full CRUD plus domain-specific actions, follows RESTful conventions such as plural nouns and nested paths for relationships, defaults to Bearer/JWT auth for protected routes with API-key headers for server-to-server or third-party cases, wraps list-endpoint responses in a pagination envelope with page/limit/sort/filter query params, and versions every path under /api/v1/ unless told otherwise.

Use it when asked about API design, API endpoints, REST APIs, or API URLs - for example "what endpoints do I need for..." or "design an API for...". It draws on a domain reference cheatsheet with pre-built resource lists for common domains like hotel booking, e-commerce, and social media so obvious resources aren't missed, plus a separate example reference for structure. For large systems with more than 8 resource groups, it offers to split the output into sections or focus on a subset first rather than dumping everything at once. Its own limitations note it should be used only when the task matches its upstream source and local project context, and that generated code, credentials, and external service behavior still need verification before being applied.

Input is a description of the system or domain needing an API, plus the user's choice between endpoints-only or a detailed design. Output is comprehensive but scannable: an endpoint list, then per-endpoint detail using tables and JSON code blocks, plus a "Base URL & Auth Summary" section. After delivering the design, it offers to hand off to a separate API Documentation skill if one is installed and use the design as its input, or to generate basic plain-text documentation covering endpoints, parameters, and responses if the user wants that without installing the other skill.

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}

Auth patterns are chosen by scenario: Bearer JWT for user-facing apps, an X-Api-Key header for server-to-server calls, no auth header for public endpoints, Bearer token plus a role check (403 if not admin) for admin endpoints, and dedicated /auth/oauth/* endpoints for OAuth flows. It is designed to compose with a separate, optional API Documentation skill rather than duplicate its job.

Developers and API architects who need a fast first draft of a REST API's shape - resources, endpoints, auth, error codes, and pagination - to accelerate design conversations or kick off implementation without hand-writing the same boilerplate spec structure every time.