Detect breaking API changes on the SERVICE surface before a PR ships, by diffing the OpenAPI/Swagger spec of the change against the base branch with oasdiff. In a service↔web↔mobile monorepo a silently-broken endpoint contract breaks consumers at runtime — this catches removed endpoints, removed/renamed fields, newly-required parameters, and type changes. Load this in the Reviewer Phase B (and Developer self-review) for SERVICE tasks that touch controllers, DTOs, or routing. Advisory — surfaces breaking changes; never auto-blocks.
How this skill is triggered — by the user, by Claude, or both
Slash command
/platform-sdlc-harness:api-contract-checkThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The service exposes an OpenAPI/Swagger document; web and mobile consume it. A
The service exposes an OpenAPI/Swagger document; web and mobile consume it. A change that removes a field or makes a parameter required is invisible to the build but breaks every consumer. oasdiff diffs two OpenAPI specs and reports breaking changes specifically.
[R<n>] comments.oasdiff CLI. /init-workspace installs it when SERVICE is present; manual:
brew install oasdiff # macOS ; Linux/Windows: release binary or `go install github.com/oasdiff/oasdiff@latest`
oasdiff --version
swagger.json (e.g. Swashbuckle CLI: dotnet swagger tofile --output swagger.json <Api.dll> v1)./swagger/v1/swagger.json endpoint.# 1. Emit the BASE spec (from the base branch checkout) → base.json
# 2. Emit the HEAD spec (from the PR branch checkout) → head.json
# 3. Diff for breaking changes only:
oasdiff breaking base.json head.json
oasdiff breaking base.json head.json --format json # machine-readable
# Full changelog (non-breaking too):
oasdiff changelog base.json head.json
In holistic review the Reviewer already has both branches available
(git diff <base>...<head>); generate each spec from the respective checkout (or
from two app runs) and diff.
Non-breaking (informational): new optional fields, new endpoints, new optional params, relaxed validation.
/v2/…) or a coordinated consumer update — not a silent edit.
If breaking is intended, the PR description must say so and name the consumer
update plan.[R<n>] WARNING (or CRITICAL if a
shipped consumer depends on it) with the consumer impact; read-only — no edits.dotnet-conventions — SERVICE API/controller conventions.migration-safety — the database-schema equivalent.react-turbo-conventions / expo-mobile-conventions — the consumers a contract break would hit.github.com/oasdiff/oasdiff.npx claudepluginhub ameenaliu/harness-platform --plugin platform-sdlc-harnessGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.