global-skills/skills/api-design/SKILL.md

name, description, scope

name	description	scope
api-design	Design or modify API routes, validated request/response schemas, error contracts, and API documentation within the existing project stack.	global

API design

1. Inspect the existing transport, schema library, auth, and error conventions. Keep domain logic independent of HTTP/framework request objects where practical.
2. Define inputs, outputs, status codes, authorization, and meaningful payload limits. Use runtime validation at untrusted boundaries; TypeScript interfaces alone do not validate requests. Derive limits from product needs and resource budgets.
3. Implement the route using existing services and data access patterns. Reuse existing dependency injection; do not introduce layers or repositories by default.
4. Preserve HTTP semantics and the project's error shape. Use Problem Details when adopting that format; otherwise document the existing structured contract. Serialize timestamps consistently with explicit timezone information.
5. Verify changed contracts and failure behavior under shared verification.

Read security guidance for affected untrusted boundaries, not as a mandatory second audit. Validation and authorization failures reject the request. A dependency fallback requires an explicit behavior contract; never infer "fail open" merely because an endpoint is internal.