api-design

Purpose

Designs or changes API contracts.

Source Skill purpose

When to use it

Use api-design when a task adds or changes an API surface. It edits the contract format the project already uses, such as OpenAPI, GraphQL, protobuf or JSON Schema, and writes API documentation only when no contract exists. Each operation covers its path, request and response shapes, errors, authorization, idempotency, pagination and versioning. Breaking and versioned changes are called out for the plan, including consumer impact and a migration path. It can also recover contract documentation from existing routes.

The existing API convention determines names, casing, error envelopes and versioning. Each changed operation receives a change class, and each removed or modified operation is checked for compatibility. The design names the handler path when code exists, or the intended location when it does not. Missing decisions about callers, retention or limits are returned as questions instead of being invented. Removal of an operation is always breaking.

Source Skill purpose

How it works

Steps of the skill, in source order

Source Flow

Define scope Read the assignment and list operations implied by its acceptance criteria.
Source Flow
Discover contracts Find the existing contract format, repository style and relevant handlers before drafting.
Source Flow
Specify operations Describe each operation's input, success, errors and authorization in the existing format.
Source Flow
Classify changes Mark operations added, modified, removed or unchanged and assess breaking behavior.
Source Flow
Write contract impact Give every breaking or versioned change a plan line with consumers and migration.
Source Flow
Write machine data Record the designed operations and their classifications in the API data file.
Source Flow
Validate the design Run the API validator and correct errors until the contract data is valid.
Source Flow
Report decisions Summarize format, operations, breaking changes, contract lines and open questions.
Source Flow

Key rules

Find and follow an existing contract before writing a new one.
Source Hard rules
Flag every breaking change against the compatibility catalog.
Source Hard rules
Prefer additive compatible operations where consumers can tolerate them.
Source Hard rules
Specify successful and error responses, authorization and request behavior for each operation.
Source Hard rules
Match the repository's naming, error envelope, pagination and versioning conventions.
Source Hard rules

Output and gate

Output

The skill definition states no output.

Source Skill definition

Gate

Validation must succeed; unreported breaking or versioned changes prevent completion.
Source Gate rule

Source