| name | migrate-hardhat2-to-hardhat3 |
| description | Systematically migrate a Hardhat V2 project to Hardhat V3, covering core changes (ESM, declarative config, hooks system, network connections) and the full plugin ecosystem (hardhat-deploy, hardhat-verify, @openzeppelin/hardhat-upgrades, and others), coverage tools, and test migration. Use when upgrading any production Hardhat V2 repository to V3. |
This skill runs the full V2→V3 migration as six sequential phases. A single agent running them top-to-bottom is the default — it handles small and medium projects (and large ones up to ~150 .ts test files on a 1M-token context window). Beyond that, or on a smaller-context harness (~200k tokens) past a trivial project, fan the file-heavy phases (4 and 5) out to sub-agents so a single context doesn't overflow mid-migration (see "Optional: sub-agent fan-out" in references/migration-conventions.md).
Before you start
- Read references/migration-conventions.md — the rules every phase depends on (no VCS commands, package-manager detection, scoping, gates, change presentation, and the optional parallel-execution model). Don't proceed until you have.
- Detect the package manager (lockfile check) and remember it for the whole migration.
- Choose the execution mode. Estimate your context window and the project size (count
.ts test files) and pick single-agent (the default) vs. sub-agent fan-out using the thresholds in the conventions doc. If you can't tell which window you're on, assume the smaller one. Most projects stay single-agent.
- Phases are strictly sequential — each depends on the previous one's output. After every phase, stop at a user checkpoint and wait for approval before continuing. Present the checkpoint in this order:
- Step done — the title of the phase just completed (e.g. Phase 1 — Project Setup) and its changes: list the changed files and surface any unexpected ones verbatim (see core rule 5 in the conventions doc).
- Suggested commit message — the checkpoint commit for the completed phase.
- Next step — the title of the phase coming next (e.g. Phase 2 — Config) and a one-line description of what it will do, or "the migration is complete" after Phase 6.
Phases
Run each phase by following its phase guide. Each ends with a gate; the checklist below is your confirmation that the phase is truly done before moving on.
Phase 1 — Project Setup → phase guide
Creates .env from templates, updates tsconfig.json for ESM, converts package.json (ESM flag, V2→V3 dependency swap, scripts).
Rewrites hardhat.config.ts to V3 declarative defineConfig (plugins, networks, custom tasks, solidity, verify, test settings).
Phase 3 — Solidity Tests → phase guide
Migrates .t.sol test files to V3 conventions. May need config changes (e.g. paths.tests.solidity to relocate Solidity test files, or paths.sources.solidity if test contracts must be compiled as sources).
Phase 4 — Source Files → phase guide
Converts all .ts (and any CommonJS .js) source files CJS→ESM and updates V2 API calls to V3 (+ TypeChain import fixes).
Phase 5 — Test Fix-Up → phase guide
Gets the .ts test suite passing under V3.
Phase 6 — Script Validation → phase guide
Interactive: the user picks package.json scripts to validate; the skill runs and fixes them one at a time.
Done
Stop and tell the user the migration is complete.
