willianbswillianbs/skills/api-contract-guardian/SKILL.md

api-contract-guardian

Skill0 starsChanged 4 months agoMITView on GitHub

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.

In this repository27 other files it gives its agents.
- adr-enforcerSkill
- ai-eval-harnessSkill
- change-impact-analyzerSkill
- code-reviewerSkill
- context-loaderSkill
- defect-analystSkill
- delivery-plannerSkill
- engineering-mentorSkill
- engineering-osSkill
- feature-implementerSkill
- guardrails-configuratorSkill
- incident-commanderSkill
- loop-engineerSkill
- migration-surgeonSkill
- model-routerSkill
- observability-designerSkill
- performance-auditorSkill
- postmortem-writerSkill
- pr-generatorSkill
- quality-gateSkill
- refactoring-advisorSkill
- requirements-grillSkill
- security-auditorSkill
- spec-validatorSkill
- tdd-executorSkill
- test-strategy-designerSkill
- threat-modelerSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Do not rewrite product requirements.
line 43
Distinctive:
Never approve silent breaking changes.
line 88
Distinctive:
Never invent OpenAPI that was not in repo without labeling it proposed.
line 89
Distinctive:
Never ignore auth/error contract changes.
line 90

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free