refactor-migrate
Refactor Migrate
Upgrade dependencies, replace deprecated APIs, and adapt to new framework or runtime versions — applicable to any language or project.
Detailed rules live in:
Core Principle
A migration changes external interfaces (library calls, runtime behavior) while keeping the application's observable business behavior intact. Every step must be verifiable independently.
When To Use
Use this skill when the task involves:
- upgrading a library or framework to a new major/minor version
- replacing deprecated APIs with their recommended successors
- bumping language or runtime version (Node, Python, Go, Java, etc.)
- switching from one library to a competing alternative (e.g., Moment → date-fns, Request → fetch)
- adapting code to breaking changes introduced by an upstream update
- removing polyfills or compatibility shims that are no longer needed after a version bump
Working Mode
- Inventory. List current versions of the targets being migrated. Identify the target versions. Read changelogs and migration guides.
- Assess impact. Search the codebase for all usage sites of the APIs, configs, or features that change. Quantify scope (file count, call count).
- Plan migration order. Dependencies have dependencies — upgrade leaf dependencies first, then work inward. Identify which changes can be done independently.
- Apply dependency upgrade rules. Update version specifiers, lock files, and configuration. See rules/dependency-upgrade.md.
- Apply API replacement rules. Replace deprecated or removed calls with new equivalents. See rules/api-replacement.md.
- Apply compatibility rules. Handle behavioral changes, type changes, and edge cases across versions. See rules/compatibility.md.
- Verify. Build, lint, and run existing tests. Flag any test failures caused by the migration.
Boundaries
- Do not change business logic during migration. Separate feature work from migration work.
- Do not upgrade unrelated dependencies in the same pass — scope to what the user asked.
- Do not remove a dependency without confirming zero remaining usage.
- Do not downgrade type safety or error handling to satisfy a new API.
- Prefer incremental migration (codemods, adapter layers) over big-bang rewrites when the change surface is large.
Default Output Expectations
- Show before/after for each API replacement.
- Note behavioral differences between old and new versions when they exist.
- Warn when a breaking change has no direct equivalent and a workaround is needed.
- When the migration is large, produce a step-by-step plan before writing code.
More from quentinhsu/skills
pr-content
Generate GitHub Pull Request title and description from branch changes. Use this skill whenever the user asks to create PR content, draft a pull request, write PR description, or says things like '生成 PR 内容', '写 PR 描述', '帮我整理 PR 标题和正文', 'generate PR content', 'write PR title and description', 'draft pull request description', 'what should my PR say', or 'help me write this PR'. Also trigger when you see requests for PR templates, PR summaries, or when the user is preparing to open a pull request.
16commit-message
Generate conventional commit messages from staged git diff. Use this skill whenever the user asks to generate a commit message, write commit text, create a conventional commit, or says things like '生成 commit', '写 commit message', '根据暂存区生成提交说明', 'generate commit message from staged diff', 'write a conventional commit', 'what should my commit say', 'help me commit this'. Also trigger when you see requests to follow Conventional Commits format or when the user has staged changes and asks about committing.
15change-pack
Generate branch name, commit message, and PR content from one shared diff context. Use this skill whenever the user asks to generate multiple git writing artifacts at once, wants to save time by analyzing changes once, or says things like '一口气生成分支名、commit、PR 内容', '链式生成 git 文案', '一次分析改动生成全部', 'generate branch + commit + PR from same diff', 'generate everything', 'all git content from this diff', 'chain generate', or 'one-shot git writing'. This is more efficient than calling individual skills separately because it reads the diff only once and reuses the context.
13branch-name
Generate Git branch names from current branch changes against a base branch. Use this skill whenever the user mentions branch naming, wants to create/rename a branch based on their work, asks for branch name suggestions, or says things like '给这个分支起个名字', '生成分支名', '根据改动起一个 branch 名', 'suggest branch name from diff', 'name this branch based on changes', 'what should I call this branch', or 'name this feature branch'. Also trigger when you see diff-based naming requests or when the user has uncommitted work and asks about branching.
13refactor-clean
Perform clean refactoring on any codebase — remove dead code, simplify logic, improve naming, extract abstractions, and reduce complexity without changing behavior. Use this skill when the user asks to clean up code, refactor for readability, reduce complexity, remove unused code, simplify conditionals, flatten nesting, rename for clarity, or says things like '重构一下这段代码', '清理无用代码', '简化逻辑', 'clean up this code', 'refactor for readability', 'reduce complexity', 'remove dead code', 'simplify this function', 'flatten nesting', or 'make this easier to read'. Also trigger when reviewing code quality or performing tech debt cleanup.
3refactor-modernize
Modernize code by replacing legacy patterns with current language features and idiomatic conventions. Use this skill when rewriting old-style code to use modern syntax, adopting new language features, replacing callbacks with async/await, using pattern matching instead of switch, applying modern iteration, or says things like '用现代写法重写', '替换旧语法', '用 async/await 重写回调', 'modernize this code', 'use modern syntax', 'replace legacy patterns', 'convert to async/await', 'use destructuring', 'apply modern idioms', or 'rewrite with current best practices'. Also trigger when adopting new edition features (Rust editions, Python 3.10+ features, ES2024, etc.).
3