API Designer walks Claude through API design in order: understand the domain, model resources, define endpoints, write the contract and plan how the API will change over time.
The contract is an OpenAPI 3.1 specification that the skill lints with Redocly and can serve from a Prism mock server. It ships a starter spec with cursor pagination, bearer authentication and RFC 7807 problem responses.
What You Get
- A resource model with relationships before any spec is written
- An OpenAPI 3.1 spec built from a copy-paste starter with cursor pagination and bearer auth
- Error responses in RFC 7807 problem format with stable type URIs
- A mock server command to test the contract with Prism
- A versioning and deprecation plan with a migration path for breaking changes
Common Use Cases
- Designing a new public REST API from a domain description
- Writing an OpenAPI spec for an existing service
- Defining a pagination and error format that every endpoint shares
- Planning a v2 of an API with a deprecation path
- Reviewing endpoint naming and status code use
What Makes It Unique
Most API prompts stop at endpoint lists. This skill adds a hard validation step, linting the spec and mocking it, and carries explicit rules such as no verbs in resource URIs, pagination on every collection and a documented error code for each failure. Separate references cover REST patterns, versioning, pagination, error handling and OpenAPI.
Under The Hood
The skill is a SKILL.md with five reference files and no scripts of its own. During a run it tells the agent to execute two npx commands, the Redocly linter on the spec and the Prism mock server, so it runs shell commands in your project, can download those npm packages, and writes the OpenAPI file there. It does not fetch web pages or call outside APIs by itself.