{"id":"e973c30e-1351-4e97-b1d4-556192487aab","shortId":"pBngJB","kind":"skill","title":"Breaking Change Detector","tagline":"Compares two versions of a codebase or API and flags all breaking changes with migration hints.","description":"# Breaking Change Detector\n\n## What this skill does\n\nThis 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.\n\nUse 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.\n\n## How to use\n\n### Claude Code / Cline\n\nCopy this file to `.agents/skills/breaking-change-detector/SKILL.md` in your project root.\n\nThen ask:\n- *\"Use the Breaking Change Detector skill to compare the old and new versions of our API.\"*\n- *\"I changed `src/auth/index.ts`. Use the Breaking Change Detector skill to find any breaking changes.\"*\n\nProvide: the old version (paste, file path, or git ref) and the new version.\n\n### Cursor\n\nAdd 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.\n\n### Codex\n\nPaste both versions clearly labeled as \"OLD VERSION\" and \"NEW VERSION\" and ask Codex to follow the instructions below.\n\n## The Prompt / Instructions for the Agent\n\nWhen asked to detect breaking changes, follow this process:\n\n### Step 1 — Establish what constitutes the public contract\n\nBefore comparing, identify what is \"public\" — i.e., what external callers or consumers depend on:\n- For a library: all exported functions, types, interfaces, and constants\n- For a REST API: all endpoints (method + path), request body shapes, response shapes, status codes, and headers\n- For a database schema: table names, column names, data types, nullability, and unique constraints\n- For a TypeScript/JavaScript module: all `export` statements\n\nChanges to internal/private code are not breaking changes unless they affect something observable from outside.\n\n### Step 2 — Categorize each difference\n\nCompare the old and new versions and classify every difference into one of these categories:\n\n**Breaking changes (must flag)**\n- Removed export, endpoint, table, or column\n- Renamed export, endpoint, table, or column (removal + add = breaking)\n- Changed function signature: removed a parameter, changed a required parameter's type, changed return type in an incompatible way\n- Changed REST response: removed a field, changed a field's type, changed a status code that callers branch on\n- Added a required field to a request body or function parameter\n- Narrowed a type (e.g., `string` → `'a' | 'b'`)\n- Changed behavior that existing callers rely on (e.g., changed sort order, changed error format)\n\n**Non-breaking changes (informational only)**\n- Added a new optional parameter (with a default value)\n- Added a new export, endpoint, or field\n- Widened a type (e.g., `'a' | 'b'` → `string`)\n- Internal refactoring with identical observable behavior\n- Performance improvements\n- New optional fields in a response\n\n### Step 3 — For each breaking change, produce a migration hint\n\nEvery breaking change entry must include:\n- What changed (old vs new)\n- Why it is breaking (what callers were relying on)\n- What callers must do to migrate (specific, actionable)\n\n### Step 4 — Format the output\n\n```markdown\n## Breaking Change Report\n\n### Summary\n- Breaking changes: N\n- Non-breaking changes: N (informational)\n\n---\n\n### Breaking Changes\n\n#### 1. [Short title]\n- **Type**: [Removed / Renamed / Signature change / Type change / Behavior change]\n- **Location**: `path/to/file.ts` or `POST /api/endpoint`\n- **Old**: [What it was before]\n- **New**: [What it is now, or \"Removed\"]\n- **Why it breaks**: [What callers were depending on]\n- **Migration**: [Exactly what callers need to change]\n\n#### 2. ...\n\n---\n\n### Non-Breaking Changes (Informational)\n\n| # | Location | Change | Notes |\n|---|----------|--------|-------|\n| 1 | `src/utils.ts` | Added `formatCurrency()` export | New addition, no action needed |\n\n---\n\n### Recommended Version Bump\n[Based on semver: MAJOR if any breaking changes exist, MINOR if only additions, PATCH if only bug fixes]\n```\n\n### Step 5 — Flag ambiguous cases\n\nIf 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.\n\n## Example\n\n**Input to Agent:**\n> \"Use the Breaking Change Detector skill. Here are the two versions of our user service interface:\n>\n> OLD:\n> ```ts\n> export function getUser(id: string): Promise<{ id: string; name: string; email: string }>\n> export function createUser(name: string, email: string): Promise<{ id: string }>\n> export function deleteUser(id: string): Promise<void>\n> ```\n>\n> NEW:\n> ```ts\n> export function getUser(id: string): Promise<{ id: string; name: string; email: string; role: string }>\n> export function createUser(input: { name: string; email: string; role: string }): Promise<{ id: string }>\n> ```\"\n\n**Output from Agent:**\n\n> ## Breaking Change Report\n>\n> ### Summary\n> - Breaking changes: 2\n> - Non-breaking changes: 1 (informational)\n>\n> ---\n>\n> ### Breaking Changes\n>\n> #### 1. `createUser` signature changed from positional args to object input\n> - **Type**: Signature change\n> - **Location**: `userService.ts`\n> - **Old**: `createUser(name: string, email: string)`\n> - **New**: `createUser(input: { name: string; email: string; role: string })`\n> - **Why it breaks**: All callers passing `createUser(\"Alice\", \"alice@example.com\")` will break at compile time. Also, `role` is now required — callers that don't provide it will fail.\n> - **Migration**: Update all call sites to `createUser({ name: \"Alice\", email: \"alice@example.com\", role: \"user\" })`. Decide on a default role value for existing callers.\n>\n> #### 2. `deleteUser` removed\n> - **Type**: Removed\n> - **Location**: `userService.ts`\n> - **Old**: `deleteUser(id: string): Promise<void>`\n> - **New**: Not present\n> - **Why it breaks**: Any caller invoking `deleteUser()` will get a compile error or runtime error.\n> - **Migration**: Find a replacement for delete functionality or soft-delete via `updateUser`. Audit all usages with `grep -r \"deleteUser\"`.\n>\n> ---\n>\n> ### Non-Breaking Changes\n>\n> | # | Location | Change | Notes |\n> |---|----------|--------|-------|\n> | 1 | `getUser` return type | Added `role: string` field to response | Additive — existing callers can ignore it |\n>\n> ### Recommended Version Bump\n> MAJOR — two breaking changes require a major version bump.\n\n## Notes\n\n- For REST APIs, also check HTTP status codes — changing a 404 to a 400 can break callers that branch on status codes.\n- For database schemas, dropping a column is always breaking even if no application code references it — other services may query directly.\n- This skill does not apply the migrations — it produces the report. Use the Migration Guide Writer skill to turn the report into a full migration guide.","tags":["breaking","change","detector","openagentskills","notysoty","agent-skills","claude","claude-code","claude-skills","cline","cursor","llm"],"capabilities":["skill","source-notysoty","skill-breaking-change-detector","topic-agent-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-cline","topic-cursor","topic-llm","topic-llm-skills","topic-skills"],"categories":["openagentskills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Notysoty/openagentskills/breaking-change-detector","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Notysoty/openagentskills","source_repo":"https://github.com/Notysoty/openagentskills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (7,015 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:20.752Z","embedding":null,"createdAt":"2026-05-18T13:20:41.130Z","updatedAt":"2026-05-18T19:13:20.752Z","lastSeenAt":"2026-05-18T19:13:20.752Z","tsv":"'/api/endpoint':543 '1':232,527,580,742,746,882 '2':317,571,737,825 '3':469 '4':507 '400':924 '404':921 '5':612 'action':505,588 'ad':393,431,440,582,886 'add':170,353 'addit':586,605,892 'affect':311 'agent':31,221,652,730 'agents/skills/breaking-change-detector/skill.md':118 'ai':183 'alic':783,811 'alice@example.com':784,813 'also':790,914 'alway':940 'ambigu':614,620,648 'api':11,39,91,140,266,913 'appli':958 'applic':945 'arg':752 'arguabl':633 'ask':124,209,223 'audit':868 'b':410,452 'base':593 'behavior':412,459,537,623 'bodi':272,400 'branch':391,929 'break':1,15,20,51,64,127,146,153,226,307,336,354,427,472,479,492,512,516,521,525,558,574,599,641,655,731,735,740,744,778,786,842,877,903,926,941 'bug':609,635 'bump':592,900,909 'call':806 'caller':53,248,390,415,494,499,560,567,627,780,795,824,844,894,927 'case':615 'catch':104 'categor':318 'categori':335 'chang':2,16,21,48,57,92,107,128,142,147,154,227,301,308,337,355,361,367,374,380,385,411,419,422,428,473,480,485,513,517,522,526,534,536,538,570,575,578,600,618,624,656,732,736,741,745,749,758,878,880,904,919 'check':915 'classifi':55,328 'claud':111 'clear':200 'client':95 'cline':113 'code':101,112,192,277,304,388,918,932,946 'codebas':9,38 'codex':196,210 'column':286,345,351,938 'compar':4,33,132,240,321 'compil':788,850 'concret':68 'constant':262 'constitut':235 'constraint':293 'consum':72,250 'context':645 'contract':106,238 'copi':114 'could':50 'createus':685,717,747,762,768,782,809 'cursor':169,182 'cursorrul':176 'data':288 'databas':282,934 'decid':816 'default':438,819 'definit':43 'delet':860,865 'deleteus':695,826,833,846,874 'depend':96,251,562 'deploy':89 'detect':225 'detector':3,22,129,148,657 'differ':320,330 'direct':29,953 'drop':936 'e.g':407,418,450,621 'email':681,688,711,721,765,772,812 'endpoint':268,342,348,444 'entri':481 'error':423,851,854 'establish':233 'even':942 'everi':47,329,478 'exact':74,565 'exampl':649 'exist':52,94,414,601,823,893 'explain':60,646 'explicit':638 'export':257,299,341,347,443,584,671,683,693,701,715 'extern':247 'fail':802 'field':379,382,396,446,464,889 'file':116,160 'find':151,856 'fix':610 'flag':13,339,613,636 'follow':212,228 'format':424,508 'formatcurr':583 'full':977 'function':258,356,402,672,684,694,702,716,861 'get':848 'getus':673,703,883 'git':163 'grep':872 'guid':968,979 'header':279 'hint':19,70,477 'http':916 'i.e':245 'id':674,677,691,696,704,707,726,834 'ident':457 'identifi':46,241 'ignor':896 'improv':461 'includ':483 'incompat':372 'inform':429,524,576,743 'input':650,718,755,769 'instruct':172,214,218 'interfac':42,260,668 'intern':454 'internal/private':303 'invok':845 'know':73 'label':201 'librari':255 'locat':539,577,759,830,879 'major':596,901,907 'markdown':511 'may':951 'method':269 'migrat':18,69,476,503,564,803,855,960,967,978 'minor':602 'modul':297 'must':338,482,500 'n':518,523 'name':285,287,679,686,709,719,763,770,810 'narrow':404 'need':77,568,589 'new':85,136,167,191,206,325,433,442,462,488,549,585,699,767,837 'non':426,520,573,739,876 'non-break':425,519,572,738,875 'note':579,881,910 'nullabl':290 'object':754 'observ':313,458 'old':134,157,189,203,323,486,544,669,761,832 'one':332 'option':434,463 'order':421 'output':510,728 'outsid':315 'packag':86 'pane':184 'paramet':360,364,403,435 'pass':781 'past':159,178,197 'patch':606 'path':161,270 'path/to/file.ts':540 'perform':460 'posit':751 'post':542 'potenti':640 'present':839 'process':230 'produc':474,962 'project':121 'promis':676,690,698,706,725,836 'prompt':217 'provid':66,155,799 'public':237,244 'publish':83 'queri':952 'r':873 'recommend':590,898 'ref':164 'refactor':455 'refer':947 'reli':416,496,628 'remov':340,352,358,377,531,555,827,829 'renam':346,532 'replac':858 'report':514,733,964,974 'request':271,399 'requir':363,395,643,794,905 'respons':274,376,467,891 'rest':265,375,912 'return':368,884 'review':102,642 'role':713,723,774,791,814,820,887 'root':122 'runtim':853 'schema':40,283,935 'semver':595 'servic':667,950 'sever':59 'shape':273,275 'share':186 'short':528 'side':193,195 'signatur':357,533,748,757 'site':807 'skill':25,28,130,149,658,955,970 'skill-breaking-change-detector' 'soft':864 'soft-delet':863 'someth':312 'sort':420 'source-notysoty' 'specif':504 'src/auth/index.ts':143 'src/utils.ts':581 'statement':300 'status':276,387,917,931 'step':231,316,468,506,611 'string':408,453,675,678,680,682,687,689,692,697,705,708,710,712,714,720,722,724,727,764,766,771,773,775,835,888 'summari':515,734 'systemat':45 'tabl':284,343,349 'time':789 'titl':529 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-cursor' 'topic-llm' 'topic-llm-skills' 'topic-skills' 'ts':670,700 'turn':972 'two':5,34,662,902 'type':259,289,366,369,384,406,449,530,535,756,828,885 'typescript/javascript':296 'unintend':105 'uniqu':292 'unless':309 'updat':79,804 'updateus':867 'usag':870 'use':80,110,125,144,653,965 'user':666,815 'userservice.ts':760,831 'valu':439,821 'version':6,35,87,137,158,168,199,204,207,326,591,663,899,908 'via':866 'vs':487 'way':373 'widen':447 'writer':969","prices":[{"id":"3315c044-cb8a-48f3-adba-09a815e610be","listingId":"e973c30e-1351-4e97-b1d4-556192487aab","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Notysoty","category":"openagentskills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:41.130Z"}],"sources":[{"listingId":"e973c30e-1351-4e97-b1d4-556192487aab","source":"github","sourceId":"Notysoty/openagentskills/breaking-change-detector","sourceUrl":"https://github.com/Notysoty/openagentskills/tree/main/skills/breaking-change-detector","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:41.130Z","lastSeenAt":"2026-05-18T19:13:20.752Z"}],"details":{"listingId":"e973c30e-1351-4e97-b1d4-556192487aab","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Notysoty","slug":"breaking-change-detector","github":{"repo":"Notysoty/openagentskills","stars":8,"topics":["agent-skills","claude","claude-code","claude-skills","cline","cursor","llm","llm-skills","skills"],"license":"mit","html_url":"https://github.com/Notysoty/openagentskills","pushed_at":"2026-03-28T06:50:19Z","description":"A  community-driven library of reusable AI agent skills for Claude Code, Cursor, Codex, Cline, and more.","skill_md_sha":"c1ef804bd6981d7d9951a03ee32c2fea0b159e38","skill_md_path":"skills/breaking-change-detector/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Notysoty/openagentskills/tree/main/skills/breaking-change-detector"},"layout":"multi","source":"github","category":"openagentskills","frontmatter":{"name":"Breaking Change Detector","description":"Compares two versions of a codebase or API and flags all breaking changes with migration hints."},"skills_sh_url":"https://skills.sh/Notysoty/openagentskills/breaking-change-detector"},"updatedAt":"2026-05-18T19:13:20.752Z"}}