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.