Migration Guide Writer — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Migration Guide Writer (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact 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).
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:
# 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:**[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]Input to Agent:
"Use the Migration Guide Writer skill. We're migrating our Express app fromjsonwebtokenv8 to v9. The main changes are:sign()callback is removed (now always synchronous),verify()now throws instead of passing error to callback, and thealgorithmoption was renamed toalgorithms(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 removedjwt.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' }); } ``>
---
>
###algorithmoption renamed toalgorithmsThe 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
>
- [ ] Updatejsonwebtokento v9:npm install jsonwebtoken@9(Effort: Automated) - [ ] Find alljwt.sign(...)calls with a callback and rewrite as synchronous (Effort: Quick) - [ ] Find alljwt.verify(...)calls with a callback and replace with try/catch (Effort: Quick) - [ ] Replacealgorithm:option withalgorithms: [...](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 fromverify()but didn't add try/catch, invalid tokens will crash your server with an unhandled exception. - Middleware scope: Make sure everyverify()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~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.