api-and-interface-design

Prefer additive changes over modifications, use a compatibility window for breaking changes, and never silently rename or remove response fields. This Skill walks through caller mapping, versioning strategy, and backward-compatibility proof with old-shape requests.

Define a default and maximum limit, choose cursor pagination for large or frequently changing collections, and enforce stable sorting. List endpoints must never return unbounded records, and filter interactions plus empty-state behavior should be documented.

Idempotency keys or dedupe records are required for retry-prone writes such as payments, subscription changes, imports, uploads, webhooks, and order creation. The response behavior for duplicates must be predictable: same response, conflict, or status lookup.

Use consistent machine-readable error codes, preserve HTTP status semantics, and differentiate validation, auth, permission, not-found, conflict, rate-limit, and dependency failures. Never leak stack traces, database names, file paths, or internal IDs to clients.

Skip it for implementation-only refactors that keep all interface behavior identical. It is intended for tasks that add or change endpoints, contracts, auth boundaries, or versioning, not internal code cleanup with no caller-visible change.