Skip to content
Skills Library
Programming · Building & coding

openapi-contract

/openapi-contract

Use when a ticket adds or changes an HTTP API and the repo keeps (or should keep) a machine-readable contract — an OpenAPI/Swagger document, JSON Schemas, generated clients or types — that must stay in lockstep with the routes and be validated in CI. Invoke for "document the endpoint", "update the OpenAPI spec", "the generated client is out of date", or "add request/response schemas".

Repository
gaffer ↗
Licence
Apache-2.0
Last repository change
29.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when a ticket adds or changes an HTTP API and the repo keeps (or should keep) a machine-readable contract — an OpenAPI/Swagger document, JSON Schemas, generated clients or types — that must stay in lockstep with the routes and be validated in CI. Invoke for "document the endpoint", "update the OpenAPI spec", "the generated client is out of date", or "add request/response schemas".

Triggers from the description

document the endpointupdate the OpenAPI specthe generated client is out of dateadd request/response schemas
Original author description

Use when a ticket adds or changes an HTTP API and the repo keeps (or should keep) a machine-readable contract — an OpenAPI/Swagger document, JSON Schemas, generated clients or types — that must stay in lockstep with the routes and be validated in CI. Invoke for "document the endpoint", "update the OpenAPI spec", "the generated client is out of date", or "add request/response schemas".

How it works

  1. Steps
  2. Done when
  3. Review checklist
  4. Capture lore
Original SKILL.md headings · 83 lines, 787 words
SKILL.md preview
---
name: openapi-contract
description: Use when a ticket adds or changes an HTTP API and the repo keeps (or should keep) a machine-readable contract — an OpenAPI/Swagger document, JSON Schemas, generated clients or types — that must stay in lockstep with the routes and be validated in CI. Invoke for "document the endpoint", "update the OpenAPI spec", "the generated client is out of date", or "add request/response schemas".
stack: [node, python, go, java, rust, csharp, kotlin, ruby]
area: backend
---

# Keep the OpenAPI contract true

An API document that is not generated from, or checked against, the running code is
fiction within a month. Keep it precise, prove the implementation matches it in tests,
and treat drift or an unannounced breaking change as a failing build. Sources: OpenAPI
Specification 3.1.x (3.2.0 published September 2025), JSON Schema 2020-12, RFC 9457
(problem details), RFC 9110 (HTTP semantics).

## Steps

1. **Find how the repo produces its contract.** Generated from route schemas (best:
   zod/pydantic/JSON Schema rendered to OpenAPI), hand-maintained and checked by a
   test, or absent. Call `search_lore` for the convention and the check command (in
   the factory itself: `node scripts/openapi.mjs --check`). Never hand-edit a generated
   document; fix the source and regenerate.
2. **Respect the document's version.** Write for the `openapi:` version the repo
   declares; do not bump it unless every consumer tool supports the new one. In 3.1,
   schemas are full JSON Schema 2020-12: use `type: [string, "null"]` not `nullable`,
   numeric `exclusiveMinimum`, `examples` (array) in schemas, and the top-level
   `webhooks` map for outbound events. 3.0 documents keep 3.0 idioms.
3. **Define the schemas where the route validates.** The same schema object validates
   input at the boundary and renders the contract, so they cannot disagree. Every field
   typed; `required` stated; formats declared (`uuid`, `date-time`, `email`); enums
   closed; string lengths and array sizes bounded; `readOnly`/`writeOnly` for
   server-set and secret fields. Request bodies reject unknown properties
   (`additionalProperties: false`) where the repo validates strictly; response schemas
   document every field the server emits.
4. **Document every response, errors included.** Success status and body; each error
   status with the repo's error envelope (RFC 9457 `application/problem+json` if the
   repo uses it) and its machine codes; `401/403` where auth applies; `422`/`400` for
   validation; `429` with rate-limit headers when limited (the `rate-limiting` skill);
   the pagination envelope and parameters for lists (the `pagination-and-filtering`
   skill); `Idempotency-Key` where accepted.
5. **Name, tag and secure operations.** Unique `operationId` consistent with siblings
   (`listTickets`, `createTicket`), a one-sentence summary, tags, and a `security`
   requirement per operation (or the global default, stated) so a reviewer can audit
   authorisation from the document alone. In the factory's own API every endpoint in
   `packages/dispatch/src/api/openapi/spec.ts` declares its capability tier
   (`public` / `read` / `full`); set it for each new route.
6. **Regenerate, lint, and diff for breaks.** Run the generator; lint with the repo's
   linter only if it is already installed (`npx --no-install @redocly/cli lint`,
   `npx --no-install @stoplight/spectral-cli lint`); never fetch one.
   Compare with the base branch without writing a file outside the worktree (the safety
   hook blocks that): `oasdiff breaking <(git show <base>:<path>) <path>` if oasdiff is
   installed, otherwise read `git diff <base> -- <path>`. Breaking:
   removing a path, operation, field or enum value from a response; adding a required
   request field; narrowing a type or constraint; changing a status code or auth. Any
   break is a versioning event (the `api-versioning` skill), not a doc update.
7. **Prove the code matches the document.** Run the repo's freshness check and its
   two-way route test (every documented path is routed; every routed path is
   documented). Validate real responses against the schema in integration tests (a
   response validator, or Schemathesis-style property tests if the repo has them), so
   a handler that returns an undocumented field or status fails. If the repo has no
   check, add the smallest one and name it in the evidence.
8. **Regenerate derived clients and types** in the same change and run their
   consumers' tests; a stale generated client is the same bug as a stale document.

## Done when

The regenerated document is committed with the code, the freshness check and lint
pass, the break comparison is clean (or the break is versioned), response validation
covers the changed operations, and each acceptance criterion has evidence via the
`record-evidence` skill (document diff, check output, contract test run — the
`contract-test` skill).

## Review checklist

- [ ] One source of truth; no hand-edited generated file.
- [ ] Every new or changed operation has typed, bounded request and response schemas.
- [ ] Every response documented, errors and `429` included, in the repo's envelope.
- [ ] `operationId` unique; `security` stated per operation.
- [ ] No unversioned breaking change against the base branch.
- [ ] Tests validate actual responses against the document; freshness check green.

## Capture lore

This skill is one of the places durable, reusable knowledge naturally surfaces:
**While regenerating the contract you learn where it lives, how it is produced and the check that keeps it honest in CI.** That kind of fact is *lore*. Capture it via the **lore-capture
protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):
call the Memory MCP `suggest_lore` once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.

Versions

RepositoryScoreLicence
This page · tmj-90/gaffer100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT

Database snapshot: 13.11.2026 · package version 4705bbaef9ae (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100verify-api-contract
    Verify that an HTTP implementation matches its OpenAPI document and fix whichever side drifted. Use after adding or changing an HTTP endpoint, route, handler, controller, response shape or status code; after editing an OpenAPI/Swagger document (openapi.yaml, openapi.json,…
  • 100flutter-openapi-client
    Discover, inspect, generate, or update Flutter and Dart API clients from Swagger or OpenAPI contracts. Use when spec inventory, operation selection, client generation, or contract drift is the task; route ordinary HTTP behavior to flutter-networking and login or token lifecycle…
  • 90dev-loop-api-client-generator
    Use when the user asks about generating API clients, OpenAPI/Swagger code generation, REST API client SDKs, or automating API client creation. Do NOT use for: writing API servers, or manual HTTP request code.
  • 100rc-openapi
    Creates or updates an OpenAPI specification by discovering the project's HTTP endpoints, request schemas, and response models from source. Use to keep an openapi.yaml in sync after API changes, or to generate a spec for an existing service. Do not use for Postman collections…
  • 100openapi
    OpenAPI/Swagger specification. Covers schema definition, paths, and documentation. Use for API documentation. USE WHEN: user mentions "OpenAPI", "Swagger", "API spec", "API documentation", "schema definition", "OpenAPI 3.0", "Swagger UI", asks about "how to write OpenAPI spec",…
  • 100api-docs
    Write reference documentation or an OpenAPI spec for a REST/HTTP API by reading its source code. Use when the user says "document the API", "write endpoint docs", "generate an OpenAPI/Swagger spec", "what endpoints do we have", or "document this route".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.