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 "Detail Design" (skipped if the user already specified this), then, for a full design, lists every endpoint before expanding each resource group into a fixed structure: method and path, a short description, a headers table, a request body JSON shape, a success response with its HTTP status code, and a relevant subset of error codes.

Use it whenever a request is about API design, endpoints, REST APIs, or API URLs - "what endpoints do I need for...", "design an API for...", and similar phrasing. It infers the resources a system needs even when the user doesn't list them, so it fits early-stage API planning more than refining an already-detailed spec.

Output follows fixed rules: cover all major resources, always include CRUD plus domain-specific actions, use RESTful conventions such as plural nouns and nested paths like /hotels/{id}/rooms, default to Bearer/JWT auth for protected routes with an API-key header option for third-party integrations, show realistic request and response JSON with field types, list only the relevant error codes per endpoint rather than pasting the full set, add pagination query params (page, limit, sort, filter) and a paginated envelope (data, pagination.total/page/limit/totalPages) for list endpoints, prefix all paths with /api/v1/ unless told otherwise, and group endpoints by resource. Auth pattern selection follows context: Authorization: Bearer <JWT> for user-facing apps, X-Api-Key for server-to-server calls, no auth header for public endpoints, and Bearer plus a role check (403 if not admin) for admin endpoints. A domain reference cheatsheet (references/domains.md) supplies pre-built resource lists for common domains like hotel booking, e-commerce, and social media, and references/testmu_example.md gives a worked example structure. After delivering the design, the skill offers to generate API documentation from it, using a separate API Documentation skill if installed, or producing basic plain-text documentation itself if not.

Chains with a separate "API Documentation" skill when installed, feeding the completed design as that skill's input; without it, the skill falls back to generating basic plain-text documentation covering endpoints, parameters, and responses itself.

Developers and product teams sketching out a new API's surface who want a complete, consistently-structured endpoint specification, including auth, pagination, and error handling, generated from a domain description rather than designed resource by resource from scratch.