API design guidance for REST, GraphQL, gRPC, and Python library interfaces. It covers how clients and services exchange data through defined requests, responses, errors, authentication, and versioning.

Use it to design endpoints, schemas, OpenAPI or Swagger specifications, GraphQL schemas, gRPC services, Python package interfaces, authentication, pagination, filtering, sorting, rate limits, and CORS.

It helps avoid unclear endpoints, incompatible data formats, weak error handling, and breaking changes. It also helps choose an API style that fits the system.

api-design — Skill for Claude Code by viktorbezdek/skillstack

Install

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.

Any agent

npx skills add viktorbezdek/skillstack --skill api-design

Clone the repo

git clone --depth 1 https://github.com/viktorbezdek/skillstack

Made for: Claude Code.

Or install api-design, the plugin that ships this one along with the rest of its 1 skill.

Wrote 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.

README.md

[![agentmods](https://agentmods.dev/badge/skills/viktorbezdek/skillstack/api-design/github.svg)](https://agentmods.dev/skills/viktorbezdek/skillstack/api-design)

Your own site

<a href="https://agentmods.dev/skills/viktorbezdek/skillstack/api-design"><img src="https://agentmods.dev/badge/skills/viktorbezdek/skillstack/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.

Your own site · 80×15

<a href="https://agentmods.dev/skills/viktorbezdek/skillstack/api-design"><img src="https://agentmods.dev/badge/skills/viktorbezdek/skillstack/api-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 114 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 2,773 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

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.00114	$0.02773
Opus 5.5	$0.00046	$0.01109
Sonnet 5.5	$0.00023	$0.00555
Haiku 4.5	$0.00011	$0.00277

Measured 1mo ago against content hash 8781b113d130, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

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.

The scan reads SKILL.md. This mod also ships 13 executable files (assets/example-config.py, assets/example-exceptions.py, scripts/api_helper.py, …), listed below but not scanned — reading those needs a real analyzer, not pattern matching.

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.

api-design/skills/api-design/SKILL.md · 338 lines

How it starts

The opening of the file, as written. The whole thing — 338 lines — stays where its author put it; the contents beside it link to each section on GitHub.

API Design

Comprehensive API design skill combining REST, GraphQL, gRPC, and Python library architecture expertise with patterns, templates, and tools for production-grade APIs.

When to Activate

Creating new API endpoints (REST, GraphQL, gRPC)
Designing resource hierarchies and schemas
Writing OpenAPI/Swagger specifications
Implementing authentication and authorization
Setting up pagination, filtering, and sorting
Configuring rate limiting and CORS
Designing Python library APIs
Reviewing API designs in pull requests

Decision Tree: API Style Selection

What are you building?
+-- CRUD resources with clear entity model? --> REST
|   Best for: resource-oriented operations, caching, wide tooling support
+-- Complex queries with varying client needs? --> GraphQL
|   Best for: over-fetching prevention, nested data, multiple client types
+-- High-throughput service-to-service? --> gRPC
|   Best for: low latency, strong typing, streaming, polyglot microservices
+-- Reusable Python package? --> Python Library API
    Best for: SDKs, internal tooling, developer experience

Quick Reference

RESTful Resource Design

URL Patterns:

/api/v1/users (plural nouns, lowercase with hyphens)
/api/v1/organizations/{org_id}/teams (hierarchical, max 2 levels)
Never use verbs: /getUsers or underscores: /user_profiles

HTTP Methods:

GET - Retrieve (safe, idempotent, cacheable)
POST - Create (returns 201 with Location header)
PUT - Replace entire resource (idempotent)
PATCH - Partial update (only changed fields)
DELETE - Remove (idempotent, returns 204)

HTTP Status Codes

Category	Code	When
Success	200	GET, PUT, PATCH success
Success	201	POST success (include Location header)
Success	204	DELETE success
Client Error	400	Malformed request
Client Error	401	Missing/invalid authentication
Client Error	403	Insufficient permissions
Client Error	404	Resource doesn't exist
Client Error	409	Duplicate resource
Client Error	422	Validation errors
Client Error	429	Rate limit exceeded
Server Error	500	Unhandled exception
Server Error	503	Database/service down

Read the full file on GitHub · 338 lines

Files

What ships with it

48 files 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.

Changes

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 · 338 lines · 114 tokens per session scan A 8781b113d130

Subscribe to this mod's changes

api-design is a skill published in the GitHub repository viktorbezdek/skillstack (14 stars, last pushed 4mo ago), licensed MIT. It adds 114 tokens to every session and 2,773 once invoked, about $0.0005 per session on Opus 5.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-08-30.

Backend and APIs Claude Code agentic anthropic claude claude-skills skills

api-security-best-practices

Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities.

lingxling/awesome-skills-cn · 29 tokens

api-patterns

API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.

lingxling/awesome-skills-cn · 28 tokens

amazon-alexa

Integracao completa com Amazon Alexa para criar skills de voz inteligentes, transformar Alexa em assistente com Claude como cerebro (projeto Auri) e integrar com AWS ecosystem (Lambda, DynamoDB, Polly, Transcribe, Lex, Smart Home).

lingxling/awesome-skills-cn · 53 tokens

api-and-interface-design

Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.

lingxling/awesome-skills-cn · 49 tokens

api-designer

Generates complete, production-ready REST API endpoint specifications for any system or domain the user describes.

lingxling/awesome-skills-cn · 23 tokens

api-sdk-generator

Generates client SDK code, API wrapper libraries, request/response models, and language-specific usage patterns for any REST API.