AgentSkillsCN

migration-planning

当用户要求规划Next.js迁移、制定迁移路线图、决定迁移顺序、安排迁移阶段，或询问“我应该按照什么顺序迁移路由？”时使用此功能。通过AST分析路由，并生成分阶段的迁移计划（.migration/plan.md）。需先进行迁移评估。

SKILL.md
--- frontmatter
name: migration-planning
description: >
  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.

Migration Planning

Create a detailed, phased migration plan based on the assessment data. The plan prioritizes low-risk routes first and handles dependencies between components.

Note: This skill creates a migration-specific plan for ordering route conversions. It is NOT the same as generic plan mode (which is for designing implementation approaches). Use THIS skill when the user says "plan this migration" in a Next.js context.

Toolkit Setup

This skill requires the nextjs-migration-toolkit skill to be installed. All migration skills depend on it for AST analysis.

bash
TOOLKIT_DIR="$(cd "$(dirname "$SKILL_PATH")/../nextjs-migration-toolkit" && pwd)"
if [ ! -f "$TOOLKIT_DIR/package.json" ]; then
  echo "ERROR: nextjs-migration-toolkit is not installed." >&2
  echo "Run: npx skills add blazity/next-migration-skills -s nextjs-migration-toolkit" >&2
  echo "Then retry this skill." >&2
  exit 1
fi
bash "$TOOLKIT_DIR/scripts/setup.sh" >/dev/null

Prerequisites

  • •Run migration-assessment first to generate .migration/assessment.md and .migration/target-version.txt.
  • •The target Next.js version must be determined. If .migration/target-version.txt doesn't exist, ask the user before proceeding.

Steps

1. Gather Route and Component Data

bash
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze routes <pagesDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze components <srcDir>
npx tsx "$TOOLKIT_DIR/src/bin/ast-tool.ts" analyze dependencies <packageJsonPath>

2. Classify Routes by Migration Difficulty

Group routes into migration waves:

Wave 1 — Static pages (lowest risk)

  • •Pages with no data fetching
  • •Pages using only getStaticProps without revalidate
  • •Server-compatible components only

Wave 2 — ISR pages

  • •Pages with getStaticProps + revalidate
  • •Pages with getStaticPaths

Wave 3 — Dynamic pages

  • •Pages with getServerSideProps
  • •Pages requiring client-side features

Wave 4 — API routes

  • •Convert API routes to route handlers
  • •Handle middleware migration

Wave 5 — Complex pages

  • •Pages with getInitialProps
  • •Pages with heavy client-side logic
  • •Pages depending on replaced packages

3. Identify Shared Dependencies

For each wave, identify:

  • •Shared components that need migration first
  • •Shared layouts that can be extracted
  • •Packages that need replacement before routes can migrate

4. Generate Migration Plan

Create a structured plan document with:

  • •Phase 0: Preparation — Install App Router deps, create app/ directory, set up root layout
  • •Phase 1-N: Route waves — Each wave with specific files to migrate and order
  • •Per-route checklist: Data fetching conversion, import updates, component classification, validation
  • •Rollback strategy: How to revert if issues arise (parallel pages/ and app/ directories)

5. Save Plan

Write the plan to .migration/plan.md in the target project. Initialize progress tracking with the state management module.