Api contract guardian

Skill willianbs/skills/api-contract-guardian

AI Engineering Operating System

Install

npx -y skills add willianbs/skills --skill api-contract-guardian

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

19 days oldThe repository was created 19 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Guards OpenAPI/proto/GraphQL contracts against breaking changes and drift from implementation. Use on API PRs and releases. Emits CONTRACT_REPORT. Never rubber-stamps breaking changes without a versioning/migration plan.

SKILL.md

2.8 KB, as published. Nobody here has run it

Purpose

Detect contract drift and breaking changes; require explicit versioning or compatibility strategy before merge.

When to Use / When NOT to Use

Use when: OpenAPI/Swagger/AsyncAPI/protobuf/GraphQL changes; API version bumps; review of public endpoints.

Do not use when: internal-only private functions with no published contract; UI-only PRs.

Preconditions

Contract files and/or implementation routes available. Prefer diff of contract + code.

Inputs / Outputs

Inputs: contract files, diff, IMPACT_REPORT (optional), CONTEXT_PACK.

Outputs: CONTRACT_REPORT

Upstream / Downstream

Upstream: change-impact-analyzer, code-reviewer, feature-implementer.

Downstream: quality-gate, delivery-planner, pr-generator, migration-surgeon.

Core Principles

Published contract is the API promise.
Breaking = removed/renamed fields, tighter types, new required fields, behavior changes that violate docs.
Additive changes preferred; otherwise version or dual-run.
Implementation must match contract (drift is a defect).
Auth and error shapes are part of the contract.
Evidence from diff/spec tools when available.
Do not rewrite product requirements.

Process

Locate contracts (openapi.yaml, proto, schema.graphql, etc.).
Diff old vs new; classify Additive | Breaking | Docs-only | Drift.
Cross-check implementation routes/handlers vs contract.
Versioning strategy — URL/header/semver/package; migration notes.
Consumer guidance from IMPACT_REPORT if present.
Decision: Block on unversioned Breaking for public APIs.

Evidence Requirements

Cite operationIds/paths/fields. Prefer machine-readable diffs.

Stop Conditions / Failure Modes

Condition	Action
Breaking public API, no version/migration	Block
Contract updated but code not (or reverse)	Revise
No contract exists for a “public API” claim	ProceedWithConditions + require contract

Severity + Confidence

Unversioned breaking public API → Critical/High.

Output Contract

## CONTRACT_REPORT
Contracts checked: ...
Changes: Additive | Breaking | Drift | Docs
Breaking details: ...
Version/migration plan: ...
Impl drift: ...
Decision: Proceed | ProceedWithConditions | Revise | Block

Handoffs

change-impact-analyzer, quality-gate, migration-surgeon, feature-implementer.

Never

Never approve silent breaking changes.
Never invent OpenAPI that was not in repo without labeling it proposed.
Never ignore auth/error contract changes.