JPeetz/agent-skills / skills/api-backend/api-and-interface-design
api-and-interface-design
VerifiedUse this skill when designing APIs, module boundaries, or any public interface. Create stable, well-documented interfaces that are hard to misuse — REST endpoints, GraphQL schemas, module contracts, component props. Covers contract-first design, error semantics, validation boundaries, idempotency, and consistent naming.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 485 B |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 9.6 KB |
| evals/evals.json | config | 2.2 KB |
evals/evals.json
View on GitHub[
{
"id": "ev001",
"description": "Contract-First design — agent writes interface contract before implementation",
"scenario": "User asks for a Task API. Agent should first write the TypeScript interface contract (TaskAPI) with method signatures and types before any implementation code.",
"expected_outcome": "Agent writes a typed interface with createTask, listTasks, getTask, updateTask, deleteTask methods with proper input/output types"
},
{
"id": "ev002",
"description": "Consistent error semantics — agent uses uniform error format",
"scenario": "User asks for error handling on a REST API endpoint. Agent should produce a single consistent error shape (code, message, details) used across all endpoints.",
"expected_outcome": "Agent produces a single APIError interface and uses it consistently in error responses with proper HTTP status codes"
},
{
"id": "ev003",
"description": "Validation boundaries — agent validates at system edges only",
"scenario": "User asks to add input validation to an API. Agent should validate at the route handler boundary using a schema parser, not scatter validation throughout internal code.",
"expected_outcome": "Agent validates at the API boundary using safeParse/zod/validators, then trusts internal code without re-validation"
},
{
"id": "ev004",
"description": "Idempotency key implementation — agent implements atomic idempotency guard",
"scenario": "User asks to make a payment endpoint idempotent. Agent should implement an idempotency key mechanism with atomic claim via unique constraint, not check-then-insert race pattern.",
"expected_outcome": "Agent implements idempotency with atomic unique constraint claim (not TOCTOU pattern), payload validation on reuse, and explicit in-flight strategy"
},
{
"id": "ev005",
"description": "Additive changes — agent extends interface without breaking consumers",
"scenario": "An existing API needs a new 'priority' field. Agent should add it as optional (backward compatible), not modify existing field types or remove fields.",
"expected_outcome": "Agent adds the new field as optional, preserves all existing required fields with their original types"
}
]Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |