breaking-change

Installation
SKILL.md

BREAKING-CHANGE — did the API break, and is it allowed to?

A renamed field or a removed property is invisible in a code review and fatal to a consumer. This skill compares the API spec consumers already use against the spec you are about to ship, and reports every breaking change with the tool — not by eye.

Rules

  • Baseline first. Keep the previous spec (the one consumers already use) under version control. Never compare against a spec you just wrote.
  • Run the tool before merging any API change. A breaking change under the same version is a FAIL.
  • A breaking change is only acceptable as a new major version, or with an explicit, recorded decision by the user. Never silently.
  • Classify every change: breaking (removed endpoint or field, renamed field, type change, a new required field, stricter validation) or non-breaking (a new endpoint, a new optional field).
  • Never report "no breaking changes" without running the tool.
  • A check that did not run is never reported as passed.

Steps, in order

1. Baseline

The previous spec lives in the repo (for example docs/api/openapi.yaml at the last released version). If there is no previous spec, there is no compatibility to break — but the first spec must then be committed as the baseline before any change.

Installs
8
GitHub Stars
1
First Seen
Nov 6, 2026