next-migration-skills

Use when adding 'use client' directives, splitting mixed components into server + client parts, or fixing RSC boundary errors like "useState only works in a Client Component." Also for migrating interactive UI (forms, modals, event handlers) to App Router.

Use when migrating getStaticProps, getServerSideProps, getStaticPaths, or API routes (pages/api/) to App Router equivalents. Also use when fixing stale data, cache behavior, or fetch errors in migrated pages.

Use when starting a Next.js Pages Router to App Router migration, evaluating migration feasibility, or auditing codebase readiness. Run this BEFORE any other migration skill.

Use when the user asks to plan a Next.js migration, create a migration roadmap, decide migration order, schedule migration phases, or asks "what order should I migrate routes?" Analyzes routes via AST and generates a phased migration plan (.migration/plan.md). Requires migration-assessment first.

Use when converting a specific page from pages/ to app/ directory, or migrating a route end-to-end (file structure, data fetching, metadata, imports). The main workhorse skill for per-route migration.

Use when checking npm package compatibility with App Router, replacing deprecated packages, or auditing dependencies before migration. Covers next/router, next/image legacy, and RSC-incompatible packages.

Required dependency for all next-migration-skills. Provides AST analysis and transform tools powered by ts-morph for analyzing routes, components, dependencies, and generating App Router code.

Use after migrating a route or completing a migration phase to verify correctness. Also use when the build breaks, tests fail, or you suspect migration regressions.