Menu
Writes clear migration guides for library upgrades, breaking API changes, or framework version bumps.
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 | 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 |
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).
Copy this file to .agents/skills/migration-guide-writer/SKILL.md in your project root.
Then ask:
Provide the changelog, breaking change list, or old vs. new API code. The more context you give, the more accurate the guide.
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.
Paste the old API code and the new API code (or a changelog listing breaking changes) along with the instructions below.
When asked to write a migration guide, follow these steps:
Gather the breaking changes. Accept input in any form:
Categorize each breaking change by type:
For every breaking change, write:
Write a step-by-step migration checklist. Order the steps so each one is safe to do before the next:
Estimate effort for each step:
Include a "Common Gotchas" section with pitfalls that are easy to miss or that cause confusing errors.
Include a "Testing Your Migration" section โ what to check after the upgrade to confirm everything works.
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]
## 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`