Menu
Compares two versions of a codebase or API and flags all breaking changes with migration hints.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Runs a systematic checklist review on any code diff or file, covering correctness, security, performance, and readability.
Writes a high-quality CLAUDE.md, .cursorrules, or .windsurfrules file that gives a coding agent the right project context, conventions, and constraints to work effectively.
Designs an eval suite for an LLM agent or pipeline including success metrics, trajectory scoring, LLM-as-judge setup, and regression test cases.
Designs a hybrid retrieval pipeline combining dense vector search and BM25 sparse search with reciprocal rank fusion, and explains when to use each configuration.
Converts a workflow description into a LangGraph node/edge graph with typed state, conditional routing, and human-in-the-loop checkpoints.
Audits an AI application for unnecessary token spend and recommends prompt caching, model routing, and token reduction techniques to cut costs.
| name | Breaking Change Detector |
| description | Compares two versions of a codebase or API and flags all breaking changes with migration hints. |
| category | coding |
| tags | ["breaking-changes","versioning","api","migration"] |
| author | simplyutils |
This skill directs the agent to compare two versions of a codebase, API schema, or interface definition and systematically identify every change that could break existing callers. It classifies each change by severity, explains why it is breaking, and provides a concrete migration hint so consumers know exactly what they need to update.
Use this before publishing a new package version, before deploying an API change that existing clients depend on, or during a code review to catch unintended contract changes.
Copy this file to .agents/skills/breaking-change-detector/SKILL.md in your project root.
Then ask:
src/auth/index.ts. Use the Breaking Change Detector skill to find any breaking changes."Provide: the old version (paste, file path, or git ref) and the new version.
Add the instructions below to your .cursorrules or paste them into the Cursor AI pane. Then share both the old and new code side by side.
Paste both versions clearly labeled as "OLD VERSION" and "NEW VERSION" and ask Codex to follow the instructions below.
When asked to detect breaking changes, follow this process:
Before comparing, identify what is "public" — i.e., what external callers or consumers depend on:
export statementsChanges to internal/private code are not breaking changes unless they affect something observable from outside.
Compare the old and new versions and classify every difference into one of these categories:
Breaking changes (must flag)
string → 'a' | 'b')Non-breaking changes (informational only)
'a' | 'b' → string)Every breaking change entry must include:
## Breaking Change Report
### Summary
- Breaking changes: N
- Non-breaking changes: N (informational)
---
### Breaking Changes
#### 1. [Short title]
- **Type**: [Removed / Renamed / Signature change / Type change / Behavior change]
- **Location**: `path/to/file.ts` or `POST /api/endpoint`
- **Old**: [What it was before]
- **New**: [What it is now, or "Removed"]
- **Why it breaks**: [What callers were depending on]
- **Migration**: [Exactly what callers need to change]
#### 2. ...
---
### Non-Breaking Changes (Informational)
| # | Location | Change | Notes |
|---|----------|--------|-------|
| 1 | `src/utils.ts` | Added `formatCurrency()` export | New addition, no action needed |
---
### Recommended Version Bump
[Based on semver: MAJOR if any breaking changes exist, MINOR if only additions, PATCH if only bug fixes]
If a change is ambiguous (e.g., a behavior change that some callers rely on but it was arguably a bug), flag it explicitly as "Potentially breaking — review required" with context explaining the ambiguity.
Input to Agent:
"Use the Breaking Change Detector skill. Here are the two versions of our user service interface:
OLD:
export function getUser(id: string): Promise<{ id: string; name: string; email: string }> export function createUser(name: string, email: string): Promise<{ id: string }> export function deleteUser(id: string): Promise<void>NEW:
export function getUser(id: string): Promise<{ id: string; name: string; email: string; role: string }> export function createUser(input: { name: string; email: string; role: string }): Promise<{ id: string }> ```"
Output from Agent:
Breaking Change Report
Summary
- Breaking changes: 2
- Non-breaking changes: 1 (informational)
Breaking Changes
1.
createUsersignature changed from positional args to object input
- Type: Signature change
- Location:
userService.ts- Old:
createUser(name: string, email: string)- New:
createUser(input: { name: string; email: string; role: string })- Why it breaks: All callers passing
createUser("Alice", "alice@example.com")will break at compile time. Also,roleis now required — callers that don't provide it will fail.- Migration: Update all call sites to
createUser({ name: "Alice", email: "alice@example.com", role: "user" }). Decide on a default role value for existing callers.2.
deleteUserremoved
- Type: Removed
- Location:
userService.ts- Old:
deleteUser(id: string): Promise<void>- New: Not present
- Why it breaks: Any caller invoking
deleteUser()will get a compile error or runtime error.- Migration: Find a replacement for delete functionality or soft-delete via
updateUser. Audit all usages withgrep -r "deleteUser".
Non-Breaking Changes
# Location Change Notes 1 getUserreturn typeAdded role: stringfield to responseAdditive — existing callers can ignore it Recommended Version Bump
MAJOR — two breaking changes require a major version bump.