home / skills / velcrafting / codex-skills / compatibility-check

compatibility-check skill

safe

This skill assesses API compatibility between versions, classifies as compatible, breaking, or unsafe, and lists breaking changes for informed shipping.

npx playbooks add skill velcrafting/codex-skills --skill compatibility-check

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: compatibility-check
description: Validate API compatibility across versions or consumers.
metadata:
  short-description: API compatibility gate
  layer: api
  mode: read-only
  idempotent: true
---

# Skill: api/compatibility-check

## Purpose
Determine whether an API change is:
- backward-compatible
- conditionally compatible
- breaking

And make that status explicit before shipping.

---

## Inputs
- Old contract
- New contract
- Known consumers (if available)

---

## Outputs
- Compatibility assessment:
  - compatible / breaking / unsafe
- Explicit list of breaking changes (if any)
- Recommendation:
  - proceed
  - version
  - block

---

## Non-goals
- Modifying contracts
- Updating clients
- Implementing migrations

---

## Workflow
1) Compare old vs new contract shapes.
2) Identify removed or behaviorally changed fields.
3) Assess consumer impact.
4) Emit a clear compatibility verdict.

---

## Checks
- All removals and type changes enumerated
- Verdict is explicit and justified

---

## Failure modes
- Missing baseline contract → block and request one.
- Ambiguous change → recommend `meta/spec-sculptor`.

---

## Telemetry
Log:
- skill: `api/compatibility-check`
- verdict
- affected_consumers
- outcome

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

FAQ

What inputs are required?

An old contract and a new contract are required; supplying known consumers is optional but recommended for impact assessment.

What happens if the baseline contract is missing?

The check blocks and requests a baseline; without a baseline the skill cannot determine compatibility reliably.

How are ambiguous changes handled?

Ambiguous or behaviorally complex changes are marked unsafe and the skill recommends consulting spec maintainers or a spec-sculptor process.