Design and review HTTP/REST (and choose between REST/GraphQL/gRPC) APIs that are contract-first, resource-oriented, backward-compatible, and secure by default. Use whenever the task touches an API surface — designing an API, adding or changing an endpoint or route, picking an HTTP method or status code, naming resources, paginating a list, versioning, deprecating a field, modeling errors, idempotency, concurrency, webhooks, or writing an OpenAPI spec. Triggers: "design an API…
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# API Design
A good API is a **contract** you can evolve without breaking the people who depend on it. Design the contract first, model resources not actions, use HTTP the way it is specified, stay backward-compatible, and make security and operability the default — not an afterthought.
This skill is protocol-agnostic at the workflow level; the canonical detail lives in `references/` and is loaded on demand.
## Read first (always)
List `learnings/` and read every file whose name looks relevant to the current task — the project's versioning policy, its error envelope, its auth model, its naming conventions, and provider-specific webhook quirks live there and override the defaults in this file. If a learning conflicts with this SKILL.md, **the learning wins** — mention it to the user.
## Tradeoff — when to apply, when to lighten up
Apply the full discipline for any API with **external or cross-team consumers, or anything that persists state**. Lighten the ceremony for a private, single-consumer endpoint you fully control on both sides and can change atomically — but never lighten the security floor (authorization, input validation, no secrets in URLs).
## Workflow
…
The line at the top of this page pins the label git:20260619.98096d2, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
GET https://markdownregistry.com/api/v1/artifacts/art_62dkfvvvrqhlifps
GET https://markdownregistry.com/api/v1/resolve?ref=cristhianzl/claude-skills-czl/api-design
GET https://markdownregistry.com/api/v1/blob/3d6d69828e2874b3f45a5c255aa02122c641ece8b057bfb05f9f32948f8b6b17
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
cristhianzl/claude-skills-czl · configs/agnostic/skills/api-design/SKILL.md · Design and review HTTP/REST (and choose between REST/GraphQL/gRPC) APIs that are contract-first, resource-oriented…
cristhianzl/claude-skills-czl · configs/agnostic/skills/building-frontend-ui/SKILL.md · Build, refactor, and review frontend UI in any framework — components, accessibility, forms, client state and data…
cristhianzl/claude-skills-czl · configs/agnostic/skills/debugging-agent-runs/SKILL.md · Recover when the AGENT itself is stuck — looping, repeating the same failed action, burning tokens/budget, overflowing…
cristhianzl/claude-skills-czl · configs/agnostic/skills/developing-features-tdd/SKILL.md · Build a new feature using strict test-driven development — UNDERSTAND → DESIGN → RED → VERIFY RED → GREEN → VERIFY…
cristhianzl/claude-skills-czl · configs/agnostic/skills/documenting-features/SKILL.md · Produce living, DDD-aligned feature documentation as a single Markdown file with 10 fixed sections — overview…
cristhianzl/claude-skills-czl · configs/agnostic/skills/exploratory-testing/SKILL.md · Run structured exploratory testing — write a charter, time-box a session, apply heuristics and oracles to discover bugs…
cristhianzl/claude-skills-czl · configs/agnostic/skills/optimizing-discoverability/SKILL.md · Optimize a site or content to be found — SEO (rank and earn the click on Google/Bing), AEO (be the direct answer in…
affaan-m/ecc · docs/es/skills/api-design/SKILL.md · Patrones de diseño REST API incluyendo nomenclatura de recursos, códigos de estado, paginación, filtrado, respuestas de…
ericrisco/rsc-harness · skills/api-design/SKILL.md · Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL…
yonatangross/orchestkit · plugins/ork/skills/api-design/SKILL.md · API wire contracts for REST and GraphQL: resource shape, versioning and deprecation, RFC 9457 errors, OpenAPI. Use when…
