Applies REST and GraphQL design principles to produce or review an API contract.
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
## What this skill does
Applies REST and GraphQL design principles to produce or review an API contract. It covers resource modelling, URL conventions, HTTP semantics, request/response schemas, error formats, versioning strategy, and authentication patterns — producing OpenAPI-compatible snippets or GraphQL schema fragments.
## When to use it
- User asks to "design an API", "review this API", or "define the endpoints for X".
- User wants to model resources and operations before writing implementation code.
- User needs an OpenAPI snippet or GraphQL schema fragment.
- User is establishing API conventions for a team or project.
## Key concepts
### REST principles
| Principle | Guidance |
| --- | --- |
| **Resource naming** | Nouns, plural, lowercase, hyphenated: `/orders`, `/line-items`. Never verbs in URLs. |
| **HTTP methods** | `GET` read, `POST` create, `PUT` full replace, `PATCH` partial update, `DELETE` remove |
| **Idempotency** | `GET`, `PUT`, `DELETE` must be idempotent. `POST` is not. `PATCH` should be designed to be. |
…
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_penha4hfflpfdz7n
GET https://markdownregistry.com/api/v1/resolve?ref=marielynneblock/arcanum-artifex/api-design
GET https://markdownregistry.com/api/v1/blob/21fb7b722bbfed2e4ddda8d721fbc6065b51f9b66a6fe41804a16148bab7155b
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.
marielynneblock/arcanum-artifex · .github/skills/markdown-link-auditor/SKILL.md · Audit Markdown links, images, and local anchors for broken relative references. Use when reviewing documentation…
marielynneblock/arcanum-artifex · skills/agentic/agent-governance-patterns/SKILL.md · Design and implement governance controls for tool-using and multi-agent AI systems, including policy enforcement…
marielynneblock/arcanum-artifex · skills/agentic/agent-owasp-compliance/SKILL.md · Assess tool-using and multi-agent AI systems against OWASP ASI-style controls, mapping evidence to prompt injection…
marielynneblock/arcanum-artifex · skills/agentic/agentic-eval/SKILL.md · Use when designing and implementing evaluation loops for AI agents, including reflection, evaluator-optimiser patterns…
marielynneblock/arcanum-artifex · skills/agentic/ai-ready/SKILL.md · Guide users to review and install the external ai-ready skill from its upstream repository. Use when the user asks to…
marielynneblock/arcanum-artifex · skills/agentic/evaluation/eval-driven-dev/SKILL.md · Build an automated evaluation pipeline that tests a Python LLM application end-to-end with pixie test — real code…
marielynneblock/arcanum-artifex · skills/agentic/first-ask/SKILL.md · Interactive task-refinement workflow that clarifies scope, deliverables, and constraints before carrying out the task…
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…
