api-design SKILL.md skillA
api-design from skillmedev/skills is an agent skill: a SKILL.md folder an AI agent loads when a task calls for it.
mdr add skillmedev/skills/api-design@git:20261005.bea4ea5Pins git:20261005.bea4ea5 in mdr.lock. Pin the fingerprint instead.
- Audit grade
- A, 17 of 17 checks passed
- Kind
- SKILL.md skill
- Repository
- skillmedev/skills
- Path
skills/api-design/SKILL.md- Versions recorded
- 3
- Latest version
- git:20261005.bea4ea5, committed Oct 5, 2026
- First version recorded
- Jul 5, 2026
- Size
- 6,895 bytes
- Repository stars
- 19
- License
- MIT
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…
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
# 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). 3. Expected collection sizes and growth. A list that can exceed ~10,000 rows rules out offset pagination. 4. Read/write ratio and latency expectations per endpoint. 5. Auth model (affects 401 vs 403 correctness). ### Step 2: name resources …
Read the whole file at its exact version.
How to install
mdr add skillmedev/skills/api-design@sha256:944dbc96ebeb80f7The line at the top of this page pins the label git:20261005.bea4ea5, 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.
[](https://markdownregistry.com/a/art_5x5gadbumdm5z7ih)
3 badge image fetches in 30 days. What the badge shows.
Versions
The registry has recorded 3 versions of this file, between Jul 5, 2026 and Oct 5, 2026, about one every 46 days.
| version | committed | commit | size | audit | |
|---|---|---|---|---|---|
| git:20261005.bea4ea5 latest | 2026-10-05 | bea4ea5 | 6,895 B | A | view · diff |
| git:20260705.a28c4ce | 2026-07-05 | a28c4ce | 6,863 B | A | view · diff |
| git:20260705.acb5571 | 2026-07-05 | acb5571 | 6,899 B | A | view |
Audit of the latest version
- pass: Frontmatter block present
- pass: Frontmatter declares a name
- pass: Frontmatter declares a description
- pass: Size between 200 bytes and 200 KB (6895 bytes)
- pass: No zero-width or bidi control characters
- pass: No instruction hidden inside an HTML comment
- pass: No link to an exfiltration or paste host
- pass: No credential-shaped string
- pass: No instruction to send local credentials anywhere
- pass: No text hidden with inline styles
- pass: No prompt-injection phrasing
- pass: No curl or wget piped into a shell
- pass: No recursive delete of root, home or parent
- pass: No instruction to read or print local credentials
- pass: No base64 blob over 200 characters
- pass: No link to a raw IP address
- pass: No script tag
Source
skillmedev/skills · 19 stars · license MIT · pushed 2026-10-13 · branch main
API
GET https://markdownregistry.com/api/v1/artifacts/art_5x5gadbumdm5z7ih GET https://markdownregistry.com/api/v1/resolve?ref=skillmedev/skills/api-design GET https://markdownregistry.com/api/v1/blob/944dbc96ebeb80f76968392b618402d4da5e9f8b317ec0fbfecc8f03937326f6
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.
Guides: the SKILL.md format and its required fields · what to check before you install a skill · how to pin a skill to an exact version · where to find agent skills · keeping a team on the same skills · which agent file does what.
More from skillmedev/skills
Every file in skillmedev/skills