mcclowes/api-design
Use when designing, reviewing, or implementing HTTP APIs — error and warning handling, resource state and lifecycle, read-endpoint structure, pagination, and authentication. Triggers on error responses and formats, response envelopes, webhook payloads, how an endpoint should fail; modelling a resource lifecycle (status fields, state machines, webhook event names, enum vs parseable string); structuring read endpoints (screen-shaped/BFF vs canonical resource, aggregation, cursor vs offset pagination); and auth design (security schemes, API keys vs bearer tokens, stepped-up tokens). Apply whenever an API surfaces a failure, state change, view of data, or auth requirement to a client.
96
90%
Does it follow best practices?
Impact
99%
1.70xAverage score across 8 eval scenarios
Passed
No known issues
API design
Opinionated patterns for designing developer-friendly HTTP APIs: error/warning handling, resource state and events, read-endpoint structure and pagination, and authentication.
Structure
SKILL.md- Main skill instructions: principles, theissuespattern, the status/event/issue split, view-vs-data endpoints, auth schemes, and design rulesreferences/error-handling.md- Full field-by-field reference for theissuesarrayreferences/event-status-design.md- Modelling and naming a resource's lifecycle: states, events, and the status/event/issue splitreferences/view-vs-data-endpoints.md- View (screen-shaped/BFF) vs data (canonical resource) endpoints, and pagination (cursor vs offset)references/auth-schemes.md- Treating security schemes as discrete, named contractsreferences/consuming-in-react.md- TypeScript types and React/SDK consumption examples
Usage
This skill is automatically discovered by Claude when relevant to the task.
- Workspace
- mcclowes
- Visibility
- Public
- Created
- Last updated
- Repository
- https://github.com/mcclowes/skills
- Publish Source
- CLI
- Badge
