{"id":"1f6d21d6-7f79-4d20-b988-83a3c7a3fa79","shortId":"XYkkDC","kind":"skill","title":"Migration Guide Writer","tagline":"Writes clear migration guides for library upgrades, breaking API changes, or framework version bumps.","description":"# Migration Guide Writer\n\n## What this skill does\n\nThis skill produces a structured, developer-friendly migration guide for any upgrade that involves breaking changes. Given the old and new versions of an API, library, or framework, it documents every breaking change with before/after code examples, produces a step-by-step migration checklist, calls out known gotchas, and estimates effort. The result is documentation your users can follow without needing to dig through release notes themselves.\n\nUse this when releasing a major version of a library, upgrading a critical dependency, or documenting a framework migration (e.g., React Router v5 → v6, Next.js 13 → 14, Postgres 15 → 16).\n\n## How to use\n\n### Claude Code / Cline\n\nCopy this file to `.agents/skills/migration-guide-writer/SKILL.md` in your project root.\n\nThen ask:\n- *\"Use the Migration Guide Writer skill to document the changes from v1 to v2 of our SDK.\"*\n- *\"Write a migration guide for upgrading from React Router v5 to v6 using the Migration Guide Writer skill.\"*\n\nProvide the changelog, breaking change list, or old vs. new API code. The more context you give, the more accurate the guide.\n\n### Cursor\n\nAdd the \"Prompt / Instructions\" section to your `.cursorrules` file. Open both the old and new API files (or paste the changelog) and ask Cursor to write the migration guide.\n\n### Codex\n\nPaste the old API code and the new API code (or a changelog listing breaking changes) along with the instructions below.\n\n## The Prompt / Instructions for the Agent\n\nWhen asked to write a migration guide, follow these steps:\n\n1. **Gather the breaking changes.** Accept input in any form:\n   - Old code + new code (diff or separate files)\n   - A changelog or release notes listing breaking changes\n   - A description of what changed\n   - If given a library name and version range, use your knowledge of that library's known changes\n\n2. **Categorize each breaking change by type:**\n   - **API rename** — a function, class, or property was renamed\n   - **Signature change** — a function's parameters or return type changed\n   - **Removal** — a feature, option, or API was removed with no replacement\n   - **Behavior change** — the same call now behaves differently\n   - **Configuration change** — config file format, env variable names, or defaults changed\n   - **Dependency change** — a peer dependency was added, removed, or version-constrained\n\n3. **For every breaking change, write:**\n   - A clear title for the change\n   - A one-sentence description of what changed and why\n   - A \"Before\" code block showing the old way\n   - An \"After\" code block showing the new way\n   - A note about any edge cases or side effects to watch for\n\n4. **Write a step-by-step migration checklist.** Order the steps so each one is safe to do before the next:\n   - Start with dependency updates (install new version, remove old packages)\n   - Then configuration changes\n   - Then API changes that can be done with search-and-replace\n   - Then behavioral changes that require manual review\n   - End with running tests and validating\n\n5. **Estimate effort** for each step:\n   - **Automated** — can be done with a codemod, sed, or find-replace\n   - **Quick** (< 1 hour) — a few files to change manually\n   - **Medium** (half day) — multiple files or some logic changes needed\n   - **Significant** (1+ days) — architectural changes or widespread usage\n\n6. **Include a \"Common Gotchas\" section** with pitfalls that are easy to miss or that cause confusing errors.\n\n7. **Include a \"Testing Your Migration\" section** — what to check after the upgrade to confirm everything works.\n\n8. **Output format:**\n\n```markdown\n# Migrating from [OLD VERSION] to [NEW VERSION]\n\n## Overview\n[2–3 sentences describing the scope of the migration and the most impactful changes.]\n\n## Prerequisites\n- [What to install or check before starting]\n\n## Breaking Changes\n\n### [Change Title]\n[One-sentence description.]\n\n**Before:**\n```[lang]\n[old code]\n```\n\n**After:**\n```[lang]\n[new code]\n```\n\n> **Note:** [any edge case or side effect]\n\n---\n[repeat for each breaking change]\n\n## Step-by-Step Migration Checklist\n\n- [ ] Step 1 — [description] *(Effort: Automated)*\n- [ ] Step 2 — [description] *(Effort: Quick)*\n...\n\n## Common Gotchas\n- **[Gotcha title]:** [Description of the trap and how to avoid it]\n\n## Testing Your Migration\n- [ ] [What to verify]\n```\n\n## Example\n\n**Input to Agent:**\n> \"Use the Migration Guide Writer skill. We're migrating our Express app from `jsonwebtoken` v8 to v9. The main changes are: `sign()` callback is removed (now always synchronous), `verify()` now throws instead of passing error to callback, and the `algorithm` option was renamed to `algorithms` (array).\"\n\n**Output from Agent:**\n> # Migrating from jsonwebtoken v8 to v9\n>\n> ## Overview\n> jsonwebtoken v9 removes all callback-based APIs in favor of synchronous calls and throws on error instead of passing errors to callbacks. Most codebases will need changes in 3–5 files.\n>\n> ## Breaking Changes\n>\n> ### `sign()` callback removed\n> `jwt.sign()` is now always synchronous. The callback form no longer works.\n>\n> **Before:**\n> ```js\n> jwt.sign(payload, secret, { expiresIn: '1h' }, (err, token) => {\n>   if (err) return next(err);\n>   res.json({ token });\n> });\n> ```\n>\n> **After:**\n> ```js\n> const token = jwt.sign(payload, secret, { expiresIn: '1h' });\n> res.json({ token });\n> ```\n>\n> > **Note:** Wrap in `try/catch` since errors now throw instead of being passed to a callback.\n>\n> ---\n>\n> ### `verify()` now throws on failure\n> Errors are thrown synchronously instead of passed as the first callback argument.\n>\n> **Before:**\n> ```js\n> jwt.verify(token, secret, (err, decoded) => {\n>   if (err) return res.status(401).json({ error: 'Invalid token' });\n>   req.user = decoded;\n>   next();\n> });\n> ```\n>\n> **After:**\n> ```js\n> try {\n>   req.user = jwt.verify(token, secret);\n>   next();\n> } catch (err) {\n>   res.status(401).json({ error: 'Invalid token' });\n> }\n> ```\n>\n> ---\n>\n> ### `algorithm` option renamed to `algorithms`\n> The option now takes an array to explicitly allow multiple algorithms.\n>\n> **Before:**\n> ```js\n> jwt.verify(token, secret, { algorithm: 'HS256' }, callback);\n> ```\n>\n> **After:**\n> ```js\n> jwt.verify(token, secret, { algorithms: ['HS256'] });\n> ```\n>\n> ## Step-by-Step Migration Checklist\n>\n> - [ ] Update `jsonwebtoken` to v9: `npm install jsonwebtoken@9` *(Effort: Automated)*\n> - [ ] Find all `jwt.sign(...)` calls with a callback and rewrite as synchronous *(Effort: Quick)*\n> - [ ] Find all `jwt.verify(...)` calls with a callback and replace with try/catch *(Effort: Quick)*\n> - [ ] Replace `algorithm:` option with `algorithms: [...]` *(Effort: Automated — find-replace)*\n> - [ ] Run your test suite and check all auth-related flows *(Effort: Quick)*\n>\n> ## Common Gotchas\n> - **Unhandled throws:** If you removed the error callback from `verify()` but didn't add try/catch, invalid tokens will crash your server with an unhandled exception.\n> - **Middleware scope:** Make sure every `verify()` call in middleware is wrapped in try/catch — not just the ones in route handlers.\n>\n> ## Testing Your Migration\n> - [ ] Login flow produces a valid token\n> - [ ] Protected routes reject requests with no token (401)\n> - [ ] Protected routes reject requests with an expired token (401)\n> - [ ] Protected routes accept a valid token and set `req.user`","tags":["migration","guide","writer","openagentskills","notysoty","agent-skills","claude","claude-code","claude-skills","cline","cursor","llm"],"capabilities":["skill","source-notysoty","skill-migration-guide-writer","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/migration-guide-writer","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,385 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:22.984Z","embedding":null,"createdAt":"2026-05-18T13:20:44.276Z","updatedAt":"2026-05-18T19:13:22.984Z","lastSeenAt":"2026-05-18T19:13:22.984Z","tsv":"'1':266,511,530,641 '13':119 '14':120 '15':122 '16':123 '1h':783,801 '2':314,584,646 '3':382,585,758 '4':432 '401':847,866,1030,1039 '5':492,759 '6':537 '7':555 '8':572 '9':915 'accept':271,1042 'accur':195 'ad':376 'add':199,982 'agent':255,672,721 'agents/skills/migration-guide-writer/skill.md':134 'algorithm':712,717,871,875,886,892,900,945,948 'allow':884 'along':245 'alway':699,769 'api':12,50,186,214,232,237,321,345,468,736 'app':684 'architectur':532 'argument':835 'array':718,881 'ask':140,221,257 'auth':962 'auth-rel':961 'autom':498,644,917,950 'avoid':661 'base':735 'before/after':60 'behav':357 'behavior':351,480 'block':407,415 'break':11,40,57,179,243,269,290,317,385,606,632,761 'bump':17 'call':71,355,741,921,934,1000 'callback':695,709,734,751,764,772,818,834,894,924,937,976 'callback-bas':733 'case':425,625 'catch':863 'categor':315 'caus':552 'chang':13,41,58,150,180,244,270,291,296,313,318,331,339,352,360,369,371,386,393,401,466,469,481,517,527,533,597,607,608,633,692,756,762 'changelog':178,219,241,285 'check':564,603,959 'checklist':70,440,639,907 'class':325 'claud':127 'clear':5,389 'cline':129 'code':61,128,187,233,238,277,279,406,414,617,621 'codebas':753 'codemod':504 'codex':228 'common':540,650,967 'config':361 'configur':359,465 'confirm':569 'confus':553 'const':795 'constrain':381 'context':190 'copi':130 'crash':987 'critic':106 'cursor':198,222 'cursorrul':206 'day':521,531 'decod':842,853 'default':368 'depend':107,370,374,456 'describ':587 'descript':293,398,613,642,647,654 'develop':31 'developer-friend':30 'didn':980 'diff':280 'differ':358 'dig':89 'document':55,81,109,148 'done':473,501 'e.g':113 'easi':547 'edg':424,624 'effect':428,628 'effort':77,494,643,648,916,929,942,949,965 'end':486 'env':364 'err':784,787,790,841,844,864 'error':554,707,745,749,809,824,849,868,975 'estim':76,493 'everi':56,384,998 'everyth':570 'exampl':62,669 'except':993 'expir':1037 'expiresin':782,800 'explicit':883 'express':683 'failur':823 'favor':738 'featur':342 'file':132,207,215,283,362,515,523,760 'find':508,918,931,952 'find-replac':507,951 'first':833 'flow':964,1018 'follow':85,263 'form':275,773 'format':363,574 'framework':15,53,111 'friend':32 'function':324,333 'gather':267 'give':192 'given':42,298 'gotcha':74,541,651,652,968 'guid':2,7,19,34,144,161,173,197,227,262,676 'half':520 'handler':1013 'hour':512 'hs256':893,901 'impact':596 'includ':538,556 'input':272,670 'instal':458,601,913 'instead':704,746,812,828 'instruct':202,248,252 'invalid':850,869,984 'involv':39 'js':778,794,837,856,888,896 'json':848,867 'jsonwebtoken':686,724,729,909,914 'jwt.sign':766,779,797,920 'jwt.verify':838,859,889,897,933 'knowledg':307 'known':73,312 'lang':615,619 'librari':9,51,103,300,310 'list':181,242,289 'logic':526 'login':1017 'longer':775 'main':691 'major':99 'make':996 'manual':484,518 'markdown':575 'medium':519 'middlewar':994,1002 'migrat':1,6,18,33,69,112,143,160,172,226,261,439,560,576,592,638,665,675,681,722,906,1016 'miss':549 'multipl':522,885 'name':301,366 'need':87,528,755 'new':46,185,213,236,278,418,459,581,620 'next':453,789,854,862 'next.js':118 'note':92,288,421,622,804 'npm':912 'old':44,183,211,231,276,410,462,578,616 'one':396,446,611,1010 'one-sent':395,610 'open':208 'option':343,713,872,877,946 'order':441 'output':573,719 'overview':583,728 'packag':463 'paramet':335 'pass':706,748,815,830 'past':217,229 'payload':780,798 'peer':373 'pitfal':544 'postgr':121 'prerequisit':598 'produc':27,63,1019 'project':137 'prompt':201,251 'properti':327 'protect':1023,1031,1040 'provid':176 'quick':510,649,930,943,966 'rang':304 're':680 'react':114,165 'reject':1025,1033 'relat':963 'releas':91,97,287 'remov':340,347,377,461,697,731,765,973 'renam':322,329,715,873 'repeat':629 'replac':350,478,509,939,944,953 'req.user':852,858,1048 'request':1026,1034 'requir':483 'res.json':791,802 'res.status':846,865 'result':79 'return':337,788,845 'review':485 'rewrit':926 'root':138 'rout':1012,1024,1032,1041 'router':115,166 'run':488,954 'safe':448 'scope':589,995 'sdk':157 'search':476 'search-and-replac':475 'secret':781,799,840,861,891,899 'section':203,542,561 'sed':505 'sentenc':397,586,612 'separ':282 'server':989 'set':1047 'show':408,416 'side':427,627 'sign':694,763 'signatur':330 'signific':529 'sinc':808 'skill':23,26,146,175,678 'skill-migration-guide-writer' 'source-notysoty' 'start':454,605 'step':66,68,265,436,438,443,497,635,637,640,645,903,905 'step-by-step':65,435,634,902 'structur':29 'suit':957 'sure':997 'synchron':700,740,770,827,928 'take':879 'test':489,558,663,956,1014 'throw':703,743,811,821,970 'thrown':826 'titl':390,609,653 'token':785,792,796,803,839,851,860,870,890,898,985,1022,1029,1038,1045 'topic-agent-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-cline' 'topic-cursor' 'topic-llm' 'topic-llm-skills' 'topic-skills' 'trap':657 'tri':857 'try/catch':807,941,983,1006 'type':320,338 'unhandl':969,992 'updat':457,908 'upgrad':10,37,104,163,567 'usag':536 'use':94,126,141,170,305,673 'user':83 'v1':152 'v2':154 'v5':116,167 'v6':117,169 'v8':687,725 'v9':689,727,730,911 'valid':491,1021,1044 'variabl':365 'verifi':668,701,819,978,999 'version':16,47,100,303,380,460,579,582 'version-constrain':379 'vs':184 'watch':430 'way':411,419 'widespread':535 'without':86 'work':571,776 'wrap':805,1004 'write':4,158,224,259,387,433 'writer':3,20,145,174,677","prices":[{"id":"b042aac1-c8cf-40a0-b77b-09efee19e4b3","listingId":"1f6d21d6-7f79-4d20-b988-83a3c7a3fa79","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:44.276Z"}],"sources":[{"listingId":"1f6d21d6-7f79-4d20-b988-83a3c7a3fa79","source":"github","sourceId":"Notysoty/openagentskills/migration-guide-writer","sourceUrl":"https://github.com/Notysoty/openagentskills/tree/main/skills/migration-guide-writer","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:44.276Z","lastSeenAt":"2026-05-18T19:13:22.984Z"}],"details":{"listingId":"1f6d21d6-7f79-4d20-b988-83a3c7a3fa79","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Notysoty","slug":"migration-guide-writer","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":"a99eef46729ae0d7d859012fa211641fc1efbbf5","skill_md_path":"skills/migration-guide-writer/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Notysoty/openagentskills/tree/main/skills/migration-guide-writer"},"layout":"multi","source":"github","category":"openagentskills","frontmatter":{"name":"Migration Guide Writer","description":"Writes clear migration guides for library upgrades, breaking API changes, or framework version bumps."},"skills_sh_url":"https://skills.sh/Notysoty/openagentskills/migration-guide-writer"},"updatedAt":"2026-05-18T19:13:22.984Z"}}