Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add halflength-ampleness75/claude-code-recipes --skill api-designgit clone --depth 1 https://github.com/halflength-ampleness75/claude-code-recipesWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/halflength-ampleness75/claude-code-recipes/api-design)<a href="https://agentmods.dev/skills/halflength-ampleness75/claude-code-recipes/api-design"><img src="https://agentmods.dev/badge/skills/halflength-ampleness75/claude-code-recipes/api-design/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/halflength-ampleness75/claude-code-recipes/api-design"><img src="https://agentmods.dev/badge/skills/halflength-ampleness75/claude-code-recipes/api-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00000 | $0.01864 |
| Opus 5.5 | $0.00000 | $0.00746 |
| Sonnet 5.5 | $0.00000 | $0.00373 |
| Haiku 4.5 | $0.00000 | $0.00186 |
Grade A, and why
api-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 228 lines — stays where its author put it; the contents beside it link to each section on GitHub.
API Design
REST API conventions: URL structure, HTTP methods, status codes, pagination, filtering, error responses, and versioning.
URL Structure
- Use nouns, not verbs — the HTTP method provides the verb
- Use plural resource names —
/users,/orders,/products - Use kebab-case for multi-word resources —
/order-items, not/orderItems - Nest resources to show relationships — max 2 levels deep
- Use query parameters for filtering, not path segments
# Good
GET /api/v1/users
GET /api/v1/users/123
GET /api/v1/users/123/orders
POST /api/v1/users
PATCH /api/v1/users/123
DELETE /api/v1/users/123
# Bad
GET /api/v1/getUsers
GET /api/v1/user/123
POST /api/v1/users/123/orders/456/items/789/notes # too deeply nested
HTTP Methods
| Method | Purpose | Idempotent | Request Body | Success Code |
|---|---|---|---|---|
| GET | Read resource(s) | Yes | No | 200 |
| POST | Create resource | No | Yes | 201 |
| PUT | Replace resource entirely | Yes | Yes | 200 |
| PATCH | Partial update | No* | Yes | 200 |
| DELETE | Remove resource | Yes | No | 204 |
*PATCH is not guaranteed idempotent, but should be designed to be when possible.
Rules
- GET requests must be safe — no side effects, no state changes
- POST for creation — return the created resource with
Locationheader - Use PATCH over PUT — partial updates are more practical than full replacement
- DELETE should be idempotent — deleting a non-existent resource returns 204, not 404
Status Codes
Use the correct status code. When in doubt, refer to this table:
Success (2xx)
| Code | Meaning | When to Use |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST that creates a resource |
| 204 | No Content | Successful DELETE, or PUT/PATCH with no response body |
Client Errors (4xx)
| Code | Meaning | When to Use |
|---|---|---|
| 400 | Bad Request | Malformed JSON, invalid field values, validation errors |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Authenticated but lacks permission |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Duplicate resource, state conflict |
| 422 | Unprocessable Entity | Valid JSON but fails business rules |
| 429 | Too Many Requests | Rate limit exceeded |
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 1mo ago First seen · 228 lines · 0 tokens per session scan A ec41ef86f211
api-design is a skill published in the GitHub repository halflength-ampleness75/claude-code-recipes (2 stars, last pushed 7d ago), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 1,864 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
agent-django-fastapi-expert
Specialist subagent: Django ORM, Django REST Framework, FastAPI async patterns, and Pydantic v2 specialist. Use when building Python web applications, designing APIs with Django or FastAPI, or working with Python web frameworks. Trigger phrases: Django, FastAPI, DRF, Django REST Framework, Pydantic, ORM, queryset…
microservices-architecture
Microservices architecture patterns and best practices. Use when designing distributed systems, breaking down monoliths, or implementing service communication.
authentication-patterns
OAuth 2.0, JWT, SSO, MFA, NextAuth/Clerk/Supabase Auth implementation patterns.
email-systems
Transactional email (Resend, SendGrid, SES), templates (React Email, MJML), deliverability (SPF/DKIM/DMARC), and inboxing best practices. Use when building email infrastructure, designing templates, or troubleshooting deliverability.
event-driven-architecture
Kafka, RabbitMQ, SQS/SNS, event sourcing, CQRS, saga patterns, dead letter queues, and idempotency. Use when designing asynchronous systems, implementing message-driven workflows, or building event streaming pipelines.
payment-integration
Stripe, RevenueCat, subscription billing, webhooks, PCI compliance, and tax. Use when integrating payments or subscriptions, handling payment webhooks, or reviewing billing and PCI scope.