Skip to content
Skills Library
Programming · Building & coding

api-contract-sync

/api-contract-sync

Keep API code, OpenAPI, Bruno, Gherkin, mocks and client types in step. Use when an endpoint, DTO, payload, status code, query parameter or auth rule changes.

Repository
Shipyard ↗
Licence
MIT
Last repository change
12.11.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 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Keep API code, OpenAPI, Bruno, Gherkin, mocks and client types in step. Use when an endpoint, DTO, payload, status code, query parameter or auth rule changes.

Original author description

Keep API code, OpenAPI, Bruno, Gherkin, mocks and client types in step. Use when an endpoint, DTO, payload, status code, query parameter or auth rule changes.

How it works

  1. Trigger
  2. Layers
  3. Steps
  4. Review gate
Original SKILL.md headings · 53 lines, 424 words
SKILL.md preview
---
name: api-contract-sync
description: Keep API code, OpenAPI, Bruno, Gherkin, mocks and client types in step. Use when an endpoint, DTO, payload, status code, query parameter or auth rule changes.
risk_level: medium
writes_files: true
requires_tools: [bru]
metadata:
  stacks: [nestjs-api, react-web, next-web, angular-web, expo-mobile]
---

# api-contract-sync

An endpoint is not done until the code, the docs, the client examples and the behavior specs agree.
Update all layers in the same task. Never defer a layer to a follow-up PR.

## Trigger

Run this skill when you change any of these:

- A route path, method, auth rule, ownership rule, status code, header or query parameter.
- A payload, DTO, schema, error shape, pagination, sorting or filtering.
- Controller or service behavior that an API shows.
- Generated shared types or API client contracts.

## Layers

Check only the layers that exist in the repository. The OpenAPI file is in `docs/api` when the project keeps one there.

1. Controller docs and DTO metadata (OpenAPI, Swagger or Scalar decorators):
   - Each endpoint documents its purpose, all response codes, its query and path parameters and its auth scheme.
   - Each DTO field has a description and an example, and says if it is required.
   - A new module is registered in the OpenAPI bootstrap, with its tags.
2. Bruno requests (`*.bru`):
   - The URL, method, query parameters, body and headers match the controller and the DTO.
   - The `docs` block and the pre-request and post-response scripts are current.
   - A new endpoint gets a new request file. A deleted endpoint loses its file. Keep the `seq` order in `folder.bru`.
3. Gherkin (`*.feature`): add or change a `Scenario` for each new or changed behavior. Update `Examples` tables.
4. Mocks and client types:
   - Mockoon: start a mock from the OpenAPI file with `npx @mockoon/cli start --data <openapi-file>`. Check that the mock answers the new shape.
   - Shared client types: update each consumer that imports the changed symbol.

## Steps

1. Read the repository `AGENTS.md`, the module README and the nearby specs and features.
2. Find every layer for the changed route or DTO.
3. Change the code and the layers together.
4. Write `not present` for a layer that does not exist. Never write `skipped`.
5. Run the smallest declared checks: lint, typecheck, the API tests, the contract tests.
6. Run the Bruno collection against the running API: `bru run <collection-dir> --env <env>`. Report each failing request.
7. After a decorator change, check that the app still starts and the OpenAPI document builds.

## Review gate

Before the handoff, answer four questions:

- Which endpoints and DTOs changed?
- Which layers did you update?
- Which layers are not present?
- Which commands ran, and did they pass?

If code changed and an existing layer did not, report the task as partial.

Versions

The database has no other skills named api-contract-sync.

Database snapshot: 13.11.2026 · package version 156ee3cc803c (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

  • 100sync-api-client
    Propagate a backend REST change all the way to a clean frontend. Regenerate the OpenAPI contract from the Kotlin controllers, run orval to regenerate the TanStack Query hooks / MSW handlers / zod schemas, fix the resulting TypeScript across the FSD slices, and leave both drift…
  • 95tl-sync
    Verifies BE/FE synchronization for a UC task. Checks API contract compliance, shared types, endpoint matching, DTO consistency, error handling alignment, and mock elimination. Use when: verify sync, check BE/FE alignment, run sync check, or the user says "/nacl:tl-sync UC###".
  • 100openapi-contract
    OpenAPI contract validation between frontend and backend. Covers type sync, endpoint validation, and contract-first development. USE WHEN: user asks about "OpenAPI validation", "API contract", "swagger sync", "frontend backend types", "API mismatch", "contract testing" DO NOT…
  • 100openapi-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…
  • 95dto-sync-patterns
    Patterns for synchronizing DTOs between frontend and backend. Covers shared types, code generation, and validation sync. USE WHEN: user asks about "DTO sync", "shared types", "frontend backend types", "type consistency", "API models" DO NOT USE FOR: type generation tools - use…
  • 95nacl-tl-sync
    Verifies BE/FE synchronization for a UC task. Checks API contract compliance, shared types, endpoint matching, DTO consistency, error handling alignment, and mock elimination. Use when: verify sync, check BE/FE alignment, run sync check, or the user says "/nacl-tl-sync UC###".

Feedback and reports

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