How do I install the API Contract Guardian skill?

Run npx skillmds@latest add willianbs/api-contract-guardian in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is API Contract Guardian safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with API Contract Guardian?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is API Contract Guardian free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published API Contract Guardian?

willianbs (@willianbs) published this skill. Their other Agent Skills are listed on their SkillMD profile.

API Contract Guardian by willianbs — Agent Skill

Name: API Contract Guardian
Author: willianbs

API Contract Guardian

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.

willianbs 09a1ef0 2 files · 3.5 KB Updated Sep 17, 2026

File contents

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.

---name: api-contract-guardiandescription: 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.---# PurposeDetect 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.# PreconditionsContract 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 Principles1. Published contract is the API promise.2. Breaking = removed/renamed fields, tighter types, new required fields, behavior changes that violate docs.3. Additive changes preferred; otherwise version or dual-run.4. Implementation must match contract (drift is a defect).5. Auth and error shapes are part of the contract.6. Evidence from diff/spec tools when available.7. Do not rewrite product requirements.# Process1. Locate contracts (openapi.yaml, proto, schema.graphql, etc.).2. Diff old vs new; classify Additive | Breaking | Docs-only | Drift.3. Cross-check implementation routes/handlers vs contract.4. Versioning strategy — URL/header/semver/package; migration notes.5. Consumer guidance from IMPACT_REPORT if present.6. Decision: Block on unversioned Breaking for public APIs.# Evidence RequirementsCite 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 + ConfidenceUnversioned breaking public API → Critical/High.# Output Contract```## CONTRACT_REPORTContracts checked: ...Changes: Additive | Breaking | Drift | DocsBreaking 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.

Frequently asked questions