version-migration-guide skill (samber): write an upgrade guide for a breaking change
Writes or audits the guide that carries a project from version N to N+1, with a detection signal and fix for every breaking change.
- Installs
- 12.4K
- on skills.sh
- Stars
- 7
- on GitHub
- Files
- 9
- besides SKILL.md
- Updated
- Nov 2026
- last repo commit
version-migration-guide produces one document: the guide that takes a working project from one version to the next with the least reading and the fewest surprises. It checks whether a guide is the right deliverable at all, inventories what breaks, orders entries by blast radius, picks a path shape (staged, single hop, compat build or sequential) and gives every breaking change a six-part entry. It ends with a cold upgrade of a real project.
It triggers on "a migration guide", "an upgrade guide", "a major version bump" or "a deprecation notice". SKILL.md sends release notes to changelog-writing. It bundles no scripts. The cold upgrade is done by a person at the keyboard, and the guide may document codemod commands.
Good for
- Maintainers shipping a major version with breaking changes
- Docs teams whose upgrade page keeps drawing support tickets
- API teams planning a deprecation, sunset or version cutover
Install version-migration-guide
Claude Code
- 1
Copy this prompt.
Install the version-migration-guide skill in Claude Code. Run this command: /plugin marketplace add samber/developer-relations-skills /plugin install developer-relations-skills@developer-relations-skills Then check that it loaded and tell me how to use it.
- 2
Paste it into Claude Code. It shows the change and asks before running it.
The README recommends installing the whole collection because its skills reference each other, and version-migration-guide names other skills in the collection to hand work to. The whole-collection routes add all 93 skills in the repo (counted from the git tree); the repo holds no hooks, agents, commands or MCP server files, and 14 of its skills bundle a script. Pick one route per agent.
From the project README. Source.
What's in the skill
When it loads
Writes or audits the migration guide for a breaking change - what breaks, ordered by blast radius, with a detection signal and before/after code per entry, a deprecation timeline, the codemod's coverage boundary, and verification by a cold upgrade of a real project. Use whenever someone mentions a migration guide, an upgrade guide, a breaking-changes page, a major version bump, "how do we tell users about v3", an API version cutover, a deprecation or sunset notice, or a codemod or compat build - even if they only say they are shipping v2. Covers libraries, SDKs, CLIs, frameworks, hosted APIs and schema runbooks. Not release notes - use samber/developer-relations-skills@changelog-writing.
Sections in SKILL.md
- Scope check
- First decide whether a guide is the right deliverable
- Pick the guide type
- Interview
- Workflow
- Entry anatomy
- Who writes it, and the gate that forces it to exist
- Audience split
- Surfaces that version independently
- Machine-readable requirements
- Invocation examples
- Pass threshold
- KPIs
- Failure modes
- References
Key facts
- Skill version
- 1.0.5 (SKILL.md metadata)
- Installs on skills.sh
- 12,434 (Nov 2, 2026)
- Last repo commit
- Nov 1, 2026
- Audits on skills.sh
- Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes
Decides whether to migrate consumers yourself instead of writing a guide.
Decides whether to migrate consumers yourself instead of writing a guide, when you control them.
Churn Rule checkAsks 11 questions, including whether usage telemetry exists on the deprecated APIs.
InterviewRuns thirteen steps from freezing scope to instrumenting adoption.
Thirteen steps from freezing scope to instrumenting adoption.
WorkflowPicks staged, single hop or compat build; sequential only when a skew policy forces it.
Chooses staged, single hop or incremental with a compat build; sequential bridges only when a skew policy imposes them.
Path shapeUses six parts per change, from a verb-prefixed heading to the escape hatch.
Six parts per change: verb-prefixed heading, affected-if line, what and why, before and after code, the fix, the escape hatch.
Entry anatomyTables what is deprecated, the warning level and the version that removes it.
A table of what is deprecated, the warning level and the version that removes it.
Deprecation timelineAdjusts the opening and deadlines for open-source, commercial and internal readers.
Audience splitRequires six checks from a cold upgrade, including completeness against the API diff.
Six checks from a cold upgrade, including completeness against the tag-to-tag API diff.
Pass thresholdLists six measures, such as tickets per thousand upgrades and the 90 day curve.
Six measures such as tickets per thousand upgrades and the 30, 60 and 90 day adoption curve.
KPIs
From the official docs
Permissions
Low risk
version-migration-guide is interview and writing instructions with no scripts, and it may save notes to devrel-context.md.
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only mode
Watch out for
It asks for a cold upgrade of a real project
SKILL.md's pass threshold has someone upgrade a real project using only the guide. That person runs your codemods and installs, so do it on a branch or a copy. github.com
It may save notes to devrel-context.md
SKILL.md tells Claude to keep task and project context in devrel-context.md when memory lives in a file, or in the memory system your tool already uses. Check the file before you commit it. github.com
The whole-set install adds 93 skills, 14 with scripts
The README says to install every skill. The git tree has 93 skill folders, and 14 of them hold .py or .sh files. This skill bundles no scripts, and the tree holds no hooks, agents or MCP config files. github.com
Technical details
| Turning on read-only | SKILL.md describes no read-only mode. |
|---|---|
| Sign-in and keys | SKILL.md names no account, key or token. |
| Scopes |
|
Questions
What does version-migration-guide do?
It writes or audits the migration guide for a breaking change. Each entry says how to detect the change, what changed, the before and after code, the fix and any escape hatch, ordered by how many readers it hits.
How do I install it?
Use the install box at the top. The README says to install every skill in the repo, because the skills point to each other. The box shows the whole-set route for each app.
Is this the same as release notes?
No. SKILL.md says the changelog says what happened and the guide says what the reader must do, and routes release notes to samber/developer-relations-skills@changelog-writing.
Does it run my codemod or upgrade my project?
SKILL.md says no to the upgrade: the consumer-side task is not this skill. It writes the document, documents codemod commands and the boundary of what they cover, and asks for a cold upgrade run by someone who did not write the guide.
Is it safe to install?
The skill bundles no scripts. API diffs, telemetry and support-ticket details you share go into your conversation. The whole-set install adds 93 skills, 14 of which bundle scripts.
Does it cover hosted APIs and databases?
Yes, in parts. SKILL.md has a section for surfaces that version independently and points to reference files for hosted APIs and for schema, cloud, mobile and browser migrations.
Information
updated Nov 2, 2026
- Repository
- samber/developer-relations-skills
- Folder
skills/version-migration-guide
Sources
Docs, issue trackers and discussions this page is built from.
Show all 3Hide
- README · github.com
- version-migration-guide SKILL.md · github.com
- LICENSE · github.com