Agent skill · magnus919
api-design-and-evolution
Design, govern, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape, ownership, duplication, lifecycle, discoverability, retirement, gateways, service meshes, north-south or east-west traffic, routing, policy, observability, or failure boundaries; defining schemas, pagination, mutations, errors, idempotency, or compatibility; or planning versioning, deprecation, and migration. Do not use for product discovery, platform operations, full security assessment, ADR authoring, or delivery gates; route those to the neighboring specialist skills.
What it needs
About 4k tokens when loaded.
What this skill does
API Design And Evolution Design an interface as a durable agreement with its consumers, not a route list. Start with the consumer job, domain meaning, authority boundary, and failure modes; then choose the interface style and contract format. Keep facts, assumptions, and policy decisions distinguishable. When to use Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or message contract, webhook, or streaming interface. Use it before implementation and again whenever consumer-visible behavior changes. When not to use Do not use this as an ADR template, a complete product-discovery method, a security assessment, or an implementation test plan. Hand those concerns to adr-authoring, product-discovery, secure-software-engineering, and verification-methodology, respectively. Workflow 1. Classify the scope. If the request spans more than one interface, start templates/api-landscape-assessment.md and read references/api-landscape-and-governance.md. If it changes where traffic is admitted, routed, observed, or isolated, read references/api-infrastructure-topologies.md. Keep portfolio findings separate from any individual contract decision. 2. Discover the agreement. State consumer jobs, domain terms and invariants, authoritative data and schema owners, actors, object/action authority boundaries, data sensitivity, and failure modes. Record unanswered questions rather than inventing policy. Start templates/api-design-brief.md. 3. Choose the interface shape. Compare interaction direction, coupling, delivery needs, query flexibility, mutation semantics, caching, observability, and evolution surface. Read references/interface-selection.md. Record the choice and rejected options in the brief; use an ADR only when the choice is consequential beyond this interface. 4. Make the contract explicit. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills magnus919/api-design-and-evolution