Code migration and upgrade assistant for AI agents. 7 technology playbooks, breaking change detection, rollback planning. Zero dependencies.
Every developer dreads the same conversation:
"We need to upgrade React 18 → 19. The changelog is 4,000 words. Our codebase has 2,000 files. Where do we even start?"
Manual migrations are a nightmare — scattered changelogs, undocumented breaking changes, and the constant fear of pushing broken code to production.
Before (manual):
1. Read the 4000-word changelog ← 😰
2. Google every error you hit ← 😩
3. Break something in production ← 💀
4. Rollback at 2am ← 🫠
5. Try again next quarter ← 🔄
After (with this skill):
1. Agent scans your codebase ← 🤖
2. Identifies every affected file ← 📋
3. Generates step-by-step migration plan ← 🗺️
4. Executes with rollback safety ← ✅
5. Tests every step ← 🧪
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ ASSESS │───▶│ PLAN │───▶│ EXECUTE │───▶│ VERIFY │───▶│ CLEAN UP │
│ │ │ │ │ │ │ │ │ │
│ • Audit │ │ • Order │ │ • Apply │ │ • Test │ │ • Remove │
│ • Deps │ │ • Risk │ │ • Test │ │ • Bench │ │ legacy │
│ • Scope │ │ • Steps │ │ • Commit │ │ • Smoke │ │ • Update │
│ • Risk │ │ • Fallback│ │ • Log │ │ • Report │ │ docs │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
Every migration follows this framework — assess the damage, plan the fix, execute with care, verify thoroughly, and clean up the mess.
| Technology | Migration Path | Key Topics |
|---|---|---|
| React | 17 → 18 → 19 | createRoot, Server Components, new hooks, automatic batching |
| Node.js | 16 → 18 → 20 | ESM migration, global fetch, WebSocket, permission model |
| Python | 3.9 → 3.10 → 3.11 → 3.12 | Pattern matching, type hints, tomllib, 60% faster |
| TypeScript | 4 → 5 | Decorators, satisfies, const type params, bundler resolution |
| Next.js | 13 → 14 → 15 | App Router, Server Actions, Turbopack, metadata API |
| Docker | Compose V1 → V2, BuildKit | Multi-platform, health checks, cache optimization |
| Tailwind CSS | v3 → v4 | CSS-first config, opacity modifiers, container queries |
Automated grep patterns and scanning commands for each technology. Know exactly which files are affected before you start.
Effort matrix, risk factors, and timeline assessment. Answer "how long will this take?" before writing a single line.
Git-based, database, Docker, and package-manager rollback procedures for every migration type. Always have a way back.
Pre-migration, during-migration, and post-migration test checklists with priority matrix. Never push broken code.
Structured report template with changes made, files affected, test results, and performance impact.
Just drop this skill into your AI agent workspace. The agent will automatically activate it when you mention migration, upgrade, or breaking changes.
Example conversation:
You: I need to migrate my React app from 18 to 19. What do I need to change?
Agent: Let me scan your codebase for affected patterns...
[Scans for ReactDOM.render, Context.Provider, ref callbacks...]
Found 12 files that need changes. Here's your migration plan:
1. Update React dependencies (0 risk)
2. Replace Context.Provider → Context (3 files)
3. Update ref callbacks with cleanup (4 files)
4. Remove defaultProps from function components (2 files)
5. Add new hooks where beneficial (3 files)
Estimated effort: 2-4 hours. Risk: LOW.
Rollback: git revert. No data migration needed.
Shall I execute step 1?
For Claude Code, OpenClaw, or any AI agent that supports markdown skills:
# Clone to your skills directory
git clone https://github.com/aptratcn/skill-migration-guide.git
# Place SKILL.md where your agent can find itThis skill is pure markdown — no npm packages, no Python libraries, no Docker images. It works by giving your AI agent the knowledge and structured processes it needs to guide migrations effectively.
Found a breaking change pattern we missed? Have a migration playbook for another technology? PRs welcome!
- Fork the repo
- Create your playbook or pattern in
SKILL.md - Test it against a real migration
- Open a PR with a clear description
MIT © 2024 aptratcn
agent-skill code-migration upgrade breaking-changes react nodejs python typescript claude-code openclaw