Agent Skills › Refactoring › migration-wizard

Refactoring

🧙 migration-wizard

Safe, incremental codebase migrations: JS→TS, Jest→Vitest, Pages→App Router and more. A free, open-source Agent Skill for Claude Code, Cline, Cursor, Codex and 75+ AI agents.

Install migration-wizard

# Claude Code (all 51 skills)
/plugin install all-skills --marketplace milad-ahmd/agent-skills

# Cursor, Codex, Cline, Windsurf, Copilot + 75 more agents
npx skills add milad-ahmd/agent-skills --skill migration-wizard

# Shell installer
curl -fsSL https://raw.githubusercontent.com/milad-ahmd/agent-skills/main/install.sh | bash -s -- migration-wizard

Included in packs: startup-cto-pack, developer-pack

What to say to your agent

When it triggers

Plans and executes large codebase migrations incrementally and safely, such as JavaScript→TypeScript, Jest→Vitest, Next.js Pages→App Router, Vue 2→3, React class→hooks, CommonJS→ESM, or any framework or major-version upgrade, verifying each step with build and tests. Use when the user asks to migrate, convert, upgrade, or port a codebase or module.

Full skill instructions (SKILL.md)

Migration Wizard

Big migrations fail when they're done as one giant PR. This skill migrates in small, verified steps.

1. Assess (read-only)

  • Identify the from → to versions and find the official migration guide and codemods for them.
  • Measure the scope by counting the affected files and APIs with search (git grep -l "<old api>" | wc -l).
  • Make sure a safety net exists: the build, the type-check, the tests and CI. If there are no tests around critical paths, recommend adding characterization tests first (see the test-gap-hunter skill).
  • Find blockers: dependencies that are incompatible with the target, custom build config, and monkey-patches.

2. Plan

Present a phased plan and wait for confirmation:

## Migration plan: Jest → Vitest (142 test files)
Phase 0: Prep: add vitest, config, keep jest running in parallel
Phase 1: Run official codemod / mechanical changes (jest.fn → vi.fn)
Phase 2: Migrate leaf modules (utils, no mocks) — 60 files
Phase 3: Modules with module mocks / timers — 70 files
Phase 4: Special cases (snapshots, custom env) — 12 files
Phase 5: Remove jest, update CI & docs
Rollback: each phase is a separate commit; revert phase N without affecting N-1

3. Execute

  • Codemods first (official tools such as @next/codemod, ts-migrate, vue-codemod, jscodeshift), then fix the rest by hand.
  • Order the work leaves first: modules with no internal dependents, then up the dependency graph.
  • After every batch: build, type-check, lint and test. Stop at the first failure and fix it before continuing.
  • One commit per phase or batch with a clear message, so each step is easy to review and revert.
  • Keep old and new running side by side when possible (for example allowJs, or both test runners) so the app stays shippable.

Recipe notes

  • JS→TS: enable allowJs and checkJs: false, rename files leaves-first, and avoid any. Use unknown plus narrowing, and add // TODO(ts): where real types are needed later. Turn on strict per directory at the end.
  • Pages→App Router: migrate route by route. Convert getServerSideProps/getStaticProps to server components and fetch caching, and add "use client" only where hooks or events are needed.
  • CommonJS→ESM: set "type": "module", add file extensions in relative imports, replace __dirname with import.meta.url, and use dynamic import() for conditional requires.

Rules

  • Never change behaviour during a migration. Refactors go in separate commits.
  • Don't delete the old setup until the new one passes everything in CI.
  • At the end, report the files migrated, what was left behind and why, and the follow-up TODOs.

View source on GitHub ⭐ Star the collection