compatibility-check_skill

Overview

This skill validates API compatibility across versions or known consumers to determine whether changes are backward-compatible, conditionally compatible, or breaking. It produces a clear verdict, enumerates breaking changes when present, and gives an action recommendation before shipping. The goal is to make compatibility decisions explicit and auditable.

How this skill works

The skill compares an existing (old) contract with a new contract shape and enumerates removals, type changes, and behavioral differences. If known consumers are provided, it maps changes to affected consumers and assesses impact. It then emits a verdict (compatible / breaking / unsafe), lists concrete breaking changes, and recommends an outcome (proceed / version / block).

When to use it

• Before merging or releasing API changes to ensure safe rollout
• During API design reviews to catch risky modifications early
• When preparing a version bump to justify semver decisions
• When validating contract changes against specific consumers
• As part of CI to gate deployments on compatibility checks

Best practices

• Supply a complete baseline (old) contract; missing baseline should block the process
• Provide known consumers to get a consumer-impact assessment
• Keep contract shapes explicit and use stable types to minimize false positives
• Treat ambiguous or complex behavioral changes as unsafe and consult spec authors
• Log verdicts and affected consumers for traceability and audits

Example use cases

• Compare v1.2 API schema to v1.3 before release to decide whether to increment the major version
• Validate a field rename to determine if it breaks downstream consumers
• Run in CI to block merges that remove required fields or change response types
• Assess the impact of narrowing a response type on known mobile and web clients
• Generate a compliance report listing exact removals and type changes for stakeholders