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 agentmods add skills/juanmhidalgo/claude-plugins/api-designnpx skills add juanmhidalgo/claude-plugins --skill api-designgit clone --depth 1 https://github.com/juanmhidalgo/claude-pluginsWrote 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/juanmhidalgo/claude-plugins/api-design)<a href="https://agentmods.dev/skills/juanmhidalgo/claude-plugins/api-design"><img src="https://agentmods.dev/badge/skills/juanmhidalgo/claude-plugins/api-design.svg" alt="Measured on agentmods" 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 | $0.00037 | $0.00763 |
| Opus 5 | $0.00018 | $0.00381 |
| Sonnet 5 | $0.00007 | $0.00153 |
| Haiku 4.5 | $0.00004 | $0.00076 |
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 today.
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 — 100 lines — stays where its author put it; the contents beside it link to each section on GitHub.
API and Interface Design
Contract-First Design
Define the interface before implementing it. The contract is the spec — implementation follows.
- Define types (input and output schemas) before writing route handlers
- Document error semantics — pick one error format and use it everywhere
- Add validation at boundaries — trust internal code after that
- Design for extension — prefer adding optional fields over modifying existing ones
Hyrum's Law
With sufficient users, all observable behaviors become depended on — regardless of your contract.
Every public behavior (including error message text, timing, ordering) becomes a de facto commitment. Design implications:
- Be intentional about what you expose
- Don't leak implementation details
- Plan for deprecation at design time
Error Semantics
Pick one strategy. Use it everywhere. Never mix patterns.
| Status | Meaning |
|---|---|
| 400 | Client sent invalid data |
| 401 | Not authenticated |
| 403 | Authenticated but not authorized |
| 404 | Resource not found |
| 409 | Conflict (duplicate, version mismatch) |
| 422 | Validation failed (semantically invalid) |
| 500 | Server error (never expose internals) |
Every error response follows the same shape:
{ "error": { "code": "MACHINE_READABLE", "message": "Human-readable", "details": {} } }
Naming Conventions
| Pattern | Convention | Example |
|---|---|---|
| REST endpoints | Plural nouns, no verbs | GET /api/tasks |
| Query params | camelCase | ?sortBy=createdAt |
| Response fields | camelCase | { createdAt, taskId } |
| Boolean fields | is/has/can prefix | isComplete |
| Enum values | UPPER_SNAKE | "IN_PROGRESS" |
Design Checklist
- Every endpoint has typed input and output schemas
- Error responses follow a single consistent format
- Validation happens at system boundaries only
- List endpoints support pagination
- New fields are additive and optional (backward compatible)
- Naming follows consistent conventions
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.
- today First seen · 100 lines · 37 tokens per session scan A 407c8c8fdccf
api-design is a skill published in the GitHub repository juanmhidalgo/claude-plugins (8 stars, last pushed 9d ago), licensed MIT. It adds 37 tokens to every session and 763 once invoked, about $0.0002 per session on Opus 5. 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-09-03.
Other skills, from other repositories
graphql-api-development
AI-powered GraphQL API design, implementation, and optimization. Covers schema-first design, resolver architecture, query optimization with DataLoader for N+1 prevention, mutation patterns with idempotency, real-time subscriptions, Apollo Federation for distributed graphs, security hardening (depth limiting, rate…
rest-api-design-patterns
Comprehensive guide for designing RESTful APIs including resource modeling, versioning strategies, HATEOAS, pagination, filtering, and HTTP best practices.
FastAPI Modern Web Development
Production-grade FastAPI development with async patterns, Pydantic v2, dependency injection, ML/AI endpoint design, and modern Python best practices for building high-performance REST APIs.
api-design
Use when designing REST or GraphQL APIs, defining endpoints, implementing pagination/filtering, handling API versioning, or establishing API documentation with OpenAPI/Swagger.
api-design-patterns
Comprehensive REST and GraphQL API design patterns with versioning, pagination, error handling, and HATEOAS principles. Use when designing APIs, defining endpoints, or architecting service contracts requiring production-grade patterns.
geo-schema
Schema.org structured data audit and generation optimized for AI discoverability — detect, validate, and generate JSON-LD markup.