CommunityCoding & Developmentgithub.com

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

What is sk-api?

sk-api is a Cursor agent skill that design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

Works with~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-api

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

API contracts

A contract is a promise to code you do not control and cannot fix. That is what makes API changes different from internal refactoring: the cost of getting it wrong is paid by someone else, at a time you do not choose.

Design

Name resources as nouns and let the method carry the verb. Model the thing, not the screen that currently displays it — a payload shaped around today's UI becomes wrong at the next redesign.

Be deliberate about what you expose. Every field you return is a field you must keep returning. Internal identifiers, row versions and implementation details leak your schema into the caller's code and freeze it there.

Make operations idempotent where the caller may retry, which is any operation reachable over a network. Give the caller an idempotency key for anything that creates or charges, so a retry after a timeout cannot double it.

Return a consistent error model: a stable machine-readable code, a human-readable message, and the field a validation failure refers to. Callers branch on the code, so it is part of the contract — changing a code is a breaking change even though the shape is unchanged.

Paginate every list, from the first version. An endpoint that returns everything works until the table grows and then fails for the customer with the most data. Prefer a cursor over an offset when rows are inserted concurrently.

What breaks a caller

Breaking, whatever the schema language allows:

  • Removing or renaming a field, an endpoint, a method, or an enum value.
  • Making an optional request field required, or narrowing what a field accepts.
  • Changing a type, including integer to string and a single value to a list.
  • Changing the meaning of an existing field while keeping its name and type — the worst kind, because nothing fails loudly and the data is quietly wrong.
  • Adding a new required field to a request.
  • Changing an error code, or an HTTP status, for an existing condition.
  • Tightening a default, or changing what happens when a field is omitted.

Safe: adding an optional request field, adding a response field, adding a new endpoint or method, adding an enum value only if every consumer already tolerates unknown values — verify that rather than assuming it.

In protobuf, never reuse or renumber a field tag, and reserve the tag and the name when you remove a field. A reused tag decodes old data into the new field and corrupts it silently.

Changing a contract safely

Add before you remove, and let both work for at least one release:

  1. Add the new field or method alongside the old one.
  2. Write both, read the new one with a fallback to the old.
  3. Migrate the consumers, and confirm each one has moved.
  4. Remove the old path in a later release.

Version when the resource genuinely changes meaning, not for every addition. A version per change multiplies the surface you must keep alive.

Deploy order

Generated code and servers deploy separately, and the gap is where the outages live. Roll out the side that tolerates both shapes first: consumers that accept the new field before producers emit it, producers that accept the new request before callers send it.

When a schema is shared through a gateway, a proxy, or generated clients, every component in the path needs regenerating and redeploying. A field added to the service but not to the layer in front of it disappears before it reaches the caller, and the service's own tests will not notice.

Verify

Check the actual consumers before changing a shape — grep the callers rather than trusting the contract's documentation.

Test the contract itself: a test that asserts the serialized shape catches an accidental rename that a unit test on the handler will miss entirely.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Related Skills