Generates RESTful and GraphQL API designs with OpenAPI specs, proper resource naming, HTTP method usage, status codes, pagination, filtering, error responses, versioning strategies, and GraphQL schema patterns. Triggers on: "design API", "create API spec", "OpenAPI", "REST endpoint design", "GraphQL schema".
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
## Instructions
### Step 1: Gather Requirements
Ask:
1. What resources does this API manage? (e.g., users, orders, products)
2. What operations are needed? (CRUD, search, bulk operations, async jobs)
3. Who consumes it? (internal services, public clients, mobile apps)
4. Auth model? (API key, OAuth2, JWT)
5. Output format preference? (OpenAPI 3.0 YAML, endpoint list, or both)
### Step 2: Resource Naming
Apply these naming conventions:
| Rule | Good | Bad |
|------|------|-----|
| Plural nouns | `/users` | `/user`, `/getUsers` |
| Nested resources | `/users/{id}/orders` | `/getUserOrders` |
| Lowercase with hyphens | `/order-items` | `/orderItems`, `/order_items` |
| No verbs in URLs | `/users/{id}/activate` (POST) | `/activateUser` |
| Max 3 levels deep | `/users/{id}/orders` | `/users/{id}/orders/{id}/items/{id}/reviews` |
For deeply nested resources, promote to top-level with query filters:
```
GET /reviews?order_id=123&user_id=456
```
### Step 3: HTTP Methods and Status Codes
Map operations to methods:
| Operation | Method | Success Code | Response Body |
|-----------|--------|-------------|---------------|
| List/Search | GET | 200 | Collection |
…
The line at the top of this page pins the label v1.0.0, 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_y25yx3zmxgxirpcq
GET https://markdownregistry.com/api/v1/resolve?ref=timwukp/agent-skills-best-practice/api-design
GET https://markdownregistry.com/api/v1/blob/567d727c51e7bdc5d9ce3ce3316f92afd364df03c5d368f73e0d5195ddbf46ca
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.
timwukp/agent-skills-best-practice · skills/skills/agentcore-harness-builder/SKILL.md · Build production-ready AWS Bedrock AgentCore Harness agents end to end — declarative model + prompt, managed/BYO…
timwukp/agent-skills-best-practice · skills/skills/ai-native-sdlc/SKILL.md · Drive a change through an AI-native software development lifecycle as a loop of committed, machine-readable artifacts —…
timwukp/agent-skills-best-practice · skills/skills/algorithmic-art/SKILL.md · Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users…
timwukp/agent-skills-best-practice · skills/skills/aws-well-architected-review/SKILL.md · Reviews AWS architectures, IaC, and design docs against the AWS Well-Architected Framework's six pillars, producing a…
timwukp/agent-skills-best-practice · skills/skills/brand-guidelines/SKILL.md · Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having…
timwukp/agent-skills-best-practice · skills/skills/canvas-design/SKILL.md · Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user…
timwukp/agent-skills-best-practice · skills/skills/doc-coauthoring/SKILL.md · Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation…
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…
