api-designer

What it does

Conveys concrete TypeScript API design guidance, including type-safe contracts, a Result type pattern, standardized ApiResponse formats, and examples for SvelteKit API routes, validation with Zod, and error handling. It includes endpoint mappings, validation schemas, error classes, and middleware patterns. It focuses on creating type-safe APIs with validation, error handling, and documentation.

How it works

The skill instructs the agent to:

• Define request/response types (e.g., CreateUserRequest, User, ApiError) and show how types serve as documentation.
• Use a Result<T, E> union for expected failures and demonstrate consumption patterns.
• Define ApiResponse<T> as a union of ApiSuccess and ApiError to standardize API responses.
• Map endpoints in an ApiEndpoints interface, detailing HTTP methods, paths, and associated request/response types.
• Provide Zod-based validation schemas (CreateUserSchema, UpdateUserSchema) and how to infer TypeScript types from schemas.
• Show error handling patterns with two categories: Result types for expected failures and ApiError/other error classes for exceptional cases.
• Present a centralized handleApiError function example to standardize error responses.
• Describe SvelteKit API routes (GET, POST, PATCH, DELETE) with examples for fetching, creating, updating, and deleting resources, integrating validation and error handling.
• Outline reusable middleware (authentication, validation, rate limiting, composition) and show how to apply them in route handlers.
• Include session management patterns (cookies, JWT, Supabase) with usage notes.
• Mention the typed database wrappers approach for persistence and provide starter wrappers for table interactions.

When to use it

Use this skill when:

• You are designing API endpoints
• You want type-safe API contracts
• You need validation and error handling patterns
• You are building SvelteKit API routes
• You seek reusable middleware patterns and API versioning guidance
• You model API behavior with a consistent response format and documented contracts

What it can touch

The skill demonstrates usage of:

• TypeScript interfaces and types (e.g., CreateUserRequest, User, ApiError)
• Zod schemas (CreateUserSchema, UpdateUserSchema)
• SvelteKit route handlers and utilities (GET/POST/PATCH/DELETE handlers, +server.ts files)
• Middleware functions (requireAuth, validateRequest, rateLimit, compose)
• Session management utilities (cookies, JWT, Supabase auth)
• Centralized error handling (handleApiError) and error classes (ApiError, ValidationError, NotFoundError, etc.)
• API endpoint mappings (ApiEndpoints)

Caveats

• The material is a code-focused guide with examples; it does not guarantee production-ready implementations and leaves room for integration details (e.g., actual DB calls, integration with your data layer).
• It specifies license and tool usage (MIT, claude-code) but does not include runtime guarantees outside the examples.
• It emphasizes Zod-based validation and TypeScript-first patterns, which require appropriate tooling in the consuming project.