# Api Contract Guard > Use when adding or changing an interface that consumers deploy separately from: an HTTP or GraphQL API endpoint, a webhook, an event or queue message, a public SDK or library API, or CLI output other tools parse, for mobile apps, partners, other services or public API users. Matches the project's existing conventions, settles the decisions that cannot be taken back once someone integrates, and cl… - **Type:** Skill - **Install:** `agentstack add skill-soumyarauth-skills-hub-api-contract-guard` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [soumyaRauth](https://agentstack.voostack.com/s/soumyarauth) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** https://github.com/soumyaRauth/skills-hub/tree/main/skills/api-contract-guard - **Website:** https://soumyarauth.github.io/skills-hub/ ## Install ```sh agentstack add skill-soumyarauth-skills-hub-api-contract-guard ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # API Contract Guard > **What does this interface promise — and which of those promises can never be > taken back?** Code is cheap to change, and a promise to someone who deploys on their own schedule is not. 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. *We'll fix it in v2* means running v1 for years. Coding agents produce endpoints well. What they miss is that this endpoint is the first in the API to use offset pagination where the others use cursors, or that `POST /refunds` without an idempotency key will refund twice on the client's first retry. The deliverable is a short block of decisions, written before the code: ``` CONTRACT GET /v1/invoices — public, API-key clients FOLLOWS error envelope {error:{code,message}} (src/api/errors.js:3) · cursor pagination ?cursor=&limit=, max 100 (GET /v1/payments) · amounts as integer minor units + currency · timestamps ISO-8601 UTC DECIDES order by (created_at, id) so cursors stay stable under inserts · status is an open enum, clients must tolerate new values · another customer's invoice returns 404, identical to a missing one CHANGE additive HANDOFF → proof-driven-dev: contract tests for page stability and cross-customer 404 ``` ## Activation **Engage when** a change adds or alters an interface that someone else deploys against: a public or partner HTTP or GraphQL API, a webhook sent or received, an event or message another service consumes, a published SDK or library API, CLI output or exit codes that scripts parse, a file format others import. Also engage on changes to the response shape, status codes, errors, pagination, authentication or versioning of such an interface. **Stay quiet when** every consumer ships in the same deploy, such as an internal endpoint only this repository's own frontend calls, unless old clients outlive a deploy (cached single-page apps, installed mobile builds). Also stay quiet for internal functions and modules, whose callers are Impact Map's concern, for UI-only work, and for refactors behind an unchanged interface. **Depth** `CONSULT`: the decisions block, then the work. `ACTIVE` when designing a new public API or making a breaking change. Never `GATING`. **Composes with** `impact-map` (who consumes the interface today, found in the repository; this skill decides what it should promise) · `proof-driven-dev` (each decision becomes a contract test) · `production-guard` (verifies idempotency and retries after the fact) · `standards-compass` (authorization, rate limiting and data exposure: the security half of an API stays there). ### Working with the other Skills Hub skills - **Loaded is not engaged.** This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not. - **Depth.** `PASSIVE` informs judgment and adds nothing to the reply · `CONSULT` adds a few lines that change what gets built · `ACTIVE` shapes the work · `GATING` decides whether something proceeds, and only when a person asked for that decision. - **Announce once.** When any skill engages at `CONSULT` or above, open the reply with one line such as `⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data`: names and a few words of reason. Never include reasoning. Add no line for `PASSIVE`, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: ` dropped: `. - **One interruption per request.** Skills that must speak before the work share one short block. Everything else arrives with the work. - **Hand off; don't absorb.** When another discipline is needed, write `HANDOFF → : []` and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so. - **Conflicts.** User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's. - **Overrides.** "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line. - **State.** Read what sibling skills recorded (`.project-compass/`, `.project-standards/`, `.proofbuild/`, `.agent-investigation/`) rather than re-deriving it. Write only your own. - **Lessons.** On engaging, read `~/.skills-hub/lessons/.md` if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: `- YYYY-MM-DD · — `. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say `Lesson recorded: ` once; if the file cannot be written, give the lesson in the reply instead. ## Non-negotiable rules 1. **Conventions are read, not assumed.** Before recommending a shape, find how this API already does it: an existing endpoint, the error helper, the OpenAPI or GraphQL schema, the SDK. Cite the location. A recommendation that ignores the house convention is a new inconsistency, however good it is in the abstract. 2. **Deviations are explicit.** When the new surface must differ, write it as a `NEW DECISION` with its reason. Never introduce a second style quietly. 3. **Consumers are evidenced.** Claim an external consumer only from evidence: a mobile app in the repository, a published OpenAPI document, versioned routes, API keys, webhook subscriptions, documentation addressed to integrators, a package published to a registry. Otherwise it is an open question. 4. **Every change is classified.** `ADDITIVE`: a new optional field, a new endpoint. `BEHAVIORAL`: the same shape with a different meaning, which is the dangerous one. `BREAKING`: a field removed, renamed or retyped; a newly required input; tighter validation; a changed status code, ordering or pagination; a changed auth scope. A behavioral change is breaking for every consumer that relied on the old meaning. 5. **Irreversible decisions are written down**, in the decisions block and, when the project keeps one, in the schema or API documentation in the same change. 6. **No best-practice lecture.** Every line in the block is a convention followed (with its location), a decision made (with its reason), or a question for a person. Anything else is deleted. 7. **Short.** The block fits in about ten lines. Detail is available when asked for. ## Workflow ### 1. The surface and its consumers Name the kind of interface: HTTP, GraphQL, webhook, event, SDK, CLI or file. Name its visibility: public, partner, internal but separately deployed, or internal and same-deploy. Then state the consumer evidence. For same-deploy only, stop here. If the code is shared, Impact Map covers its callers. ### 2. Harvest the conventions Find two or three existing interfaces of the same kind, and read off: - naming and casing, and ID format - the error envelope and code vocabulary - pagination style, parameter names and maximum page size - filtering and sorting syntax - authentication and scopes - idempotency header - versioning scheme - timestamps and time zones, money representation - null versus absent, envelopes versus bare arrays - rate-limit headers - webhook signing and retry schedule Each becomes a `FOLLOWS` line with its location. If nothing comparable exists, say so: this surface sets the convention, and that is itself a decision. ### 3. Decide what cannot be taken back `references/contract-decisions.md` lists the decisions per interface kind, and what goes wrong later when each is left implicit. The ones that come up most: - **Any interface:** identifiers, field names, types, nullability, whether an enum is open, machine-readable error codes, default ordering. - **Writes:** idempotency and retry safety, concurrency control, partial success in batch operations. - **Lists:** page stability under inserts, maximum page size, and whether to return totals, which are expensive to compute and impossible to withdraw. - **Webhooks and events:** at-least-once delivery and the event id receivers deduplicate on, ordering, signing with a timestamp and replay window, the retry schedule, payload versioning. ### 4. Classify a change to an existing contract Go field by field: `ADDITIVE`, `BEHAVIORAL` or `BREAKING`. A breaking change needs a stated migration path, and `references/compatibility.md` has the usual ones: add alongside and deprecate, a new version, dual-emit for events, a sunset date. Also say how consumers find out. ### 5. Write it down, then hand off Put the decisions block before the work. Update the contract document the repository keeps in the same change. Hand the decisions to `proof-driven-dev` as contract tests: the shape, error codes, page stability, idempotent retry, and signature verification. ## What this skill is not - **Not an API style guide.** The house style is whatever this repository already does. The skill enforces consistency with it, not a preference. - **Not a security review.** Authorization depth, rate limiting and data exposure belong to Standards Compass. This skill states which principal the contract lets see what, and hands the rest over. - **Not an impact map.** It decides what an interface should promise. Impact Map finds who, in this repository, already depends on what it promises now. ## References - `references/contract-decisions.md` — the decisions per interface kind, and what goes wrong later without them - `references/compatibility.md` — additive, behavioral and breaking changes, and migration paths ## Worked examples `examples/public-list-endpoint.md` — a public list API that follows the house conventions · `examples/outgoing-webhook.md` — a webhook's delivery contract · `examples/breaking-rename.md` — a field rename that a separate service consumes · `examples/internal-endpoint.md` — the endpoint that gets no contract block. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** [soumyaRauth/skills-hub](https://github.com/soumyaRauth/skills-hub) - **License:** MIT - **Homepage:** https://soumyarauth.github.io/skills-hub/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-soumyarauth-skills-hub-api-contract-guard - Seller: https://agentstack.voostack.com/s/soumyarauth - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.