migration-guide-writer

name	Migration Guide Writer
description	Writes clear migration guides for library upgrades, breaking API changes, or framework version bumps.
category	writing
tags	["migration","documentation","breaking-changes","upgrades"]
author	simplyutils

Migration Guide Writer

What this skill does

This 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.

Use 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).

How to use

Claude Code / Cline

Copy this file to .agents/skills/migration-guide-writer/SKILL.md in your project root.

Then ask:

• "Use the Migration Guide Writer skill to document the changes from v1 to v2 of our SDK."
• "Write a migration guide for upgrading from React Router v5 to v6 using the Migration Guide Writer skill."

Provide the changelog, breaking change list, or old vs. new API code. The more context you give, the more accurate the guide.

Cursor

Add 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.

Codex

Paste the old API code and the new API code (or a changelog listing breaking changes) along with the instructions below.

The Prompt / Instructions for the Agent

When asked to write a migration guide, follow these steps:

1. Gather the breaking changes. Accept input in any form:

   • Old code + new code (diff or separate files)
   • A changelog or release notes listing breaking changes
   • A description of what changed
   • If given a library name and version range, use your knowledge of that library's known changes

2. Categorize each breaking change by type:

   • API rename — a function, class, or property was renamed
   • Signature change — a function's parameters or return type changed
   • Removal — a feature, option, or API was removed with no replacement
   • Behavior change — the same call now behaves differently
   • Configuration change — config file format, env variable names, or defaults changed
   • Dependency change — a peer dependency was added, removed, or version-constrained

3. For every breaking change, write:

   • A clear title for the change
   • A one-sentence description of what changed and why
   • A "Before" code block showing the old way
   • An "After" code block showing the new way
   • A note about any edge cases or side effects to watch for

4. Write a step-by-step migration checklist. Order the steps so each one is safe to do before the next:

   • Start with dependency updates (install new version, remove old packages)
   • Then configuration changes
   • Then API changes that can be done with search-and-replace
   • Then behavioral changes that require manual review
   • End with running tests and validating

5. Estimate effort for each step:

   • Automated — can be done with a codemod, sed, or find-replace
   • Quick (< 1 hour) — a few files to change manually
   • Medium (half day) — multiple files or some logic changes needed
   • Significant (1+ days) — architectural changes or widespread usage

6. Include a "Common Gotchas" section with pitfalls that are easy to miss or that cause confusing errors.

7. Include a "Testing Your Migration" section — what to check after the upgrade to confirm everything works.

8. Output format:

# Migrating from [OLD VERSION] to [NEW VERSION]

## Overview
[2–3 sentences describing the scope of the migration and the most impactful changes.]

## Prerequisites
- [What to install or check before starting]

## Breaking Changes

### [Change Title]
[One-sentence description.]

**Before:**
```[lang]
[old code]

After:

[new code]

Note: [any edge case or side effect]

---

[repeat for each breaking change]

Step-by-Step Migration Checklist

• Step 1 — [description] (Effort: Automated)
• Step 2 — [description] (Effort: Quick) ...

Common Gotchas

• [Gotcha title]: [Description of the trap and how to avoid it]

Testing Your Migration

• [What to verify]

## Example

**Input to Agent:**
> "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)."

**Output from Agent:**
> # Migrating from jsonwebtoken v8 to v9
>
> ## Overview
> 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.
>
> ## Breaking Changes
>
> ### `sign()` callback removed
> `jwt.sign()` is now always synchronous. The callback form no longer works.
>
> **Before:**
> ```js
> jwt.sign(payload, secret, { expiresIn: '1h' }, (err, token) => {
>   if (err) return next(err);
>   res.json({ token });
> });
> ```
>
> **After:**
> ```js
> const token = jwt.sign(payload, secret, { expiresIn: '1h' });
> res.json({ token });
> ```
>
> > **Note:** Wrap in `try/catch` since errors now throw instead of being passed to a callback.
>
> ---
>
> ### `verify()` now throws on failure
> Errors are thrown synchronously instead of passed as the first callback argument.
>
> **Before:**
> ```js
> jwt.verify(token, secret, (err, decoded) => {
>   if (err) return res.status(401).json({ error: 'Invalid token' });
>   req.user = decoded;
>   next();
> });
> ```
>
> **After:**
> ```js
> try {
>   req.user = jwt.verify(token, secret);
>   next();
> } catch (err) {
>   res.status(401).json({ error: 'Invalid token' });
> }
> ```
>
> ---
>
> ### `algorithm` option renamed to `algorithms`
> The option now takes an array to explicitly allow multiple algorithms.
>
> **Before:**
> ```js
> jwt.verify(token, secret, { algorithm: 'HS256' }, callback);
> ```
>
> **After:**
> ```js
> jwt.verify(token, secret, { algorithms: ['HS256'] });
> ```
>
> ## Step-by-Step Migration Checklist
>
> - [ ] Update `jsonwebtoken` to v9: `npm install jsonwebtoken@9` *(Effort: Automated)*
> - [ ] Find all `jwt.sign(...)` calls with a callback and rewrite as synchronous *(Effort: Quick)*
> - [ ] Find all `jwt.verify(...)` calls with a callback and replace with try/catch *(Effort: Quick)*
> - [ ] Replace `algorithm:` option with `algorithms: [...]` *(Effort: Automated — find-replace)*
> - [ ] Run your test suite and check all auth-related flows *(Effort: Quick)*
>
> ## Common Gotchas
> - **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.
> - **Middleware scope:** Make sure every `verify()` call in middleware is wrapped in try/catch — not just the ones in route handlers.
>
> ## Testing Your Migration
> - [ ] Login flow produces a valid token
> - [ ] Protected routes reject requests with no token (401)
> - [ ] Protected routes reject requests with an expired token (401)
> - [ ] Protected routes accept a valid token and set `req.user`