Skill · before anyone integrates

API Contract Guard

Code is cheap to change; a promise to someone who deploys on their own schedule is not. This settles what an API, webhook or event promises — before the promise is made by accident.

Soumya Rauth · Creator & maintainer

npx skills add soumyaRauth/skills-hub --skill api-contract-guard

The problem

“we’ll fix it in v2” → running v1 for years

Once a mobile build ships, a partner integrates, or a webhook receiver is written against a payload, every field name, status code and retry behavior carries weight.

Agents build endpoints well. What they miss is that this one is the first in the API to use offset pagination where the rest use cursors — or that a POST without an idempotency key will act twice on the client’s first retry.

When it activates

No slash command needed. Installed, it is loaded when a request needs it and stays out of the way otherwise — and when it does shape the work, one ⚡ line says so. How the skills work together →

Engages	An interface others deploy against is added or changed: a public or partner API, a webhook, an event, an SDK, CLI output that scripts parse.
Stays quiet	Internal functions, UI-only work, and endpoints whose every consumer ships in the same deploy.
Depth	A decisions block before the work. A fuller design for a new public API or a breaking change. Never a gate.
Works with	Impact Map, ProofBuild, Production Guard, Standards Compass

What it produces

CONTRACT  GET /v1/invoices — public, API-key clients
FOLLOWS   error envelope (src/api/errors.js:3) · cursor pagination, max 100
          (GET /v1/payments) · integer minor units + currency · ISO-8601 UTC
DECIDES   order by (created_at, id) so cursors stay stable · status is an
          open enum · another customer’s invoice returns 404, like a missing one
CHANGE    additive
HANDOFF → proof-driven-dev: contract tests for page stability and cross-customer 404

Every line is a convention followed, with its location; a decision made, with its reason; or a question for a person. There is no style guide in it but the one the repository already has.

Additive, behavioral, breaking

Label	Examples
Additive	A new endpoint, a new optional field, a new value on an enum documented as open
Behavioral	The same field with a different meaning — the dangerous one, treated as breaking
Breaking	A field removed, renamed or retyped; tighter validation; a changed status code, ordering or pagination

The label is about consumers, not the diff: renaming one field in an event is a one-word change, and breaking for a service that deploys on its own schedule. A breaking change gets a migration path in which every step is safe to deploy.

Where it fits

Impact Map finds who in this repository depends on an interface today; this decides what it should promise. Production Guard checks idempotency after the code exists, and Standards Compass keeps the security half — authorization depth, rate limits, exposure.