API Design
Purpose
Define a consumer-centered contract with precise semantics, failure behavior, authorization, compatibility, and operability before or alongside implementation.
Workspace protocol
Read references/workspaces.md once per agent task before selecting or creating workflow artifacts; reuse it unless repository scope or task authority changes. This skill owns only the task-specific behavior below.
Inputs
- Consumer use cases, domain language, invariants, and quality constraints
- Existing APIs, conventions, clients, schemas, auth model, and versioning policy
- Expected scale, consistency, latency, and lifecycle needs
Outputs
- Contract for operations, messages, fields, errors, auth, pagination, idempotency, and compatibility as applicable
- Examples for normal, boundary, and failure cases
- Implementation and migration considerations without speculative internals
Rules
- Model domain capabilities, not current database tables or UI screens.
- Define presence, nullability, units, ordering, time semantics, identifiers, and error meanings explicitly.
- Design retries, idempotency, concurrency, pagination, rate limits, and partial failure where relevant.
- Apply least privilege and avoid leaking internal or sensitive data.
- Prefer additive evolution; identify every known consumer before breaking changes.
- Do not implement unless requested.
Decision-log updates
Record public contract choices, compatibility policy, naming or semantic decisions likely to recur, idempotency and consistency guarantees, and rejected alternatives with consumer impact.
When durable state is approved, append contract choices and compatibility consequences to the selected work item's decisions.md; otherwise include them in the final response.
Escalate to the human
Escalate when consumer requirements conflict, authorization ownership is unclear, semantics imply legal or financial commitments, a breaking change lacks a migration path, or reliability and consistency tradeoffs need product or platform ownership.
1---2name: api-design3description: Use when creating or changing an HTTP, RPC, event, webhook, library, or internal service contract and consumers need a stable, evolvable interface.4---56# API Design78## Purpose910Define a consumer-centered contract with precise semantics, failure behavior, authorization, compatibility, and operability before or alongside implementation.1112## Workspace protocol1314Read `references/workspaces.md` once per agent task before selecting or creating workflow artifacts; reuse it unless repository scope or task authority changes. This skill owns only the task-specific behavior below.1516## Inputs1718- Consumer use cases, domain language, invariants, and quality constraints19- Existing APIs, conventions, clients, schemas, auth model, and versioning policy20- Expected scale, consistency, latency, and lifecycle needs2122## Outputs2324- Contract for operations, messages, fields, errors, auth, pagination, idempotency, and compatibility as applicable25- Examples for normal, boundary, and failure cases26- Implementation and migration considerations without speculative internals2728## Rules2930- Model domain capabilities, not current database tables or UI screens.31- Define presence, nullability, units, ordering, time semantics, identifiers, and error meanings explicitly.32- Design retries, idempotency, concurrency, pagination, rate limits, and partial failure where relevant.33- Apply least privilege and avoid leaking internal or sensitive data.34- Prefer additive evolution; identify every known consumer before breaking changes.35- Do not implement unless requested.3637## Decision-log updates3839Record public contract choices, compatibility policy, naming or semantic decisions likely to recur, idempotency and consistency guarantees, and rejected alternatives with consumer impact.40When durable state is approved, append contract choices and compatibility consequences to the selected work item's decisions.md; otherwise include them in the final response.4142## Escalate to the human4344Escalate when consumer requirements conflict, authorization ownership is unclear, semantics imply legal or financial commitments, a breaking change lacks a migration path, or reliability and consistency tradeoffs need product or platform ownership.
nono911