Individual skill

api-design

Designs REST API surfaces - resource naming, HTTP method and status-code semantics, error shapes, pagination, and filtering - and delivers an endpoint spec a consumer can build against without asking questions. Use when someone asks "how should I name this endpoint", "what status code should this return", "should this be PUT or PATCH", "how do I paginate this list", or is reviewing an API before it ships to external consumers. Do NOT use for planning breaking-change rollouts and deprecation windows - use api-versioning-strategist instead; for GraphQL type and resolver design - use graphql-schema instead; for generating client SDKs from an existing spec - use api-client-generator instead; for designing inbound webhook endpoints - use webhook-receiver-hardener instead.

skills/api-design/SKILL.md

Read pinned source

Source commit 97a13607d669157a4a16d5ba79b77f208319f7b9

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: Yes
Repository scan complete: No
Skill scan complete: Yes
Observed behavior: Instructions only
Last checked: Nov 6, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 24
Repository last updated: Oct 13, 2026
License: MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

claude Repository topic
claude-skills Repository topic
skill-me Repository topic
design Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

SKILL.mdcore · 6,895 bytes

Read excerpt


# REST API Design

APIs are products: the consumer's mental model, not your database schema, decides the shape. The costly mistake this skill prevents is shipping an inconsistent surface - mixed naming, wrong status codes, offset pagination on a growing table - that every consumer then hardcodes around, making it effectively unfixable once integrated.

## Operating procedure

Work in this order. Resources come before methods because method semantics depend on what the resource is; error and pagination contracts come before the spec is written because retrofitting them breaks consumers.

### Step 1: gather inputs

Collect before designing. Label any assumption as a guess.

1. The consumers: internal services, first-party clients, or external developers. External consumers raise the consistency bar - default to external if unknown.
2. The core nouns of the domain and which ones own which (drives nesting).