apirev-contractlisted
Install: claude install-skill vivekbhange-hub/api-reverse-skill
# apirev-contract: catch API drift before users do
An inferred spec goes stale the day the backend ships. This skill answers two questions with
evidence: does today's traffic still match the spec (`validate`), and would this spec change
break existing clients (`diff`). Both produce a Markdown or JSON report and can fail a CI job.
## Inputs
- `validate`: `api/openapi.json` plus a newly captured HAR, scrubbed with `apirev-capture`.
- `diff`: two spec files, typically the committed one and a newly inferred or edited one.
- Commands below say `python3`; on Windows use `python` (or `py -3`).
## Outputs
- `api/contract/validate-<date>.md` or `api/contract/diff-<date>.md` (use today's date).
- Exit code 1 when `--fail-on` is hit, for CI.
## Steps
1. **Validate fresh traffic against the spec.**
```
python3 "${CLAUDE_SKILL_DIR}/contract.py" validate --spec api/openapi.json \
--har api/capture-new.scrubbed.har -o api/contract/validate-2026-11-07.md
```
Levels:
- **breaking**: required field missing, type changed, null where not nullable, a field the
spec forbids.
- **warning**: endpoint not in the spec, status code not in the spec, value outside an enum,
content type not in the spec.
- **info**: field present in traffic but not in the spec.
Identical findings are merged with a count in the "Seen" column.
2. **Diff two specs.** To see what changed since the committed spec, infer a new one into a
scratch folder first, then compare:
```