migrate-hardhat2-to-hardhat3
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.
How do I install this agent skill?
npx skills add https://github.com/nomicfoundation/hardhat-skills --skill migrate-hardhat2-to-hardhat3Is this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a legitimate migration utility for upgrading Hardhat projects from version 2 to 3, authored by Nomic Foundation. It follows official procedures for ESM conversion, dependency management, and configuration updates. No malicious behavior or security violations were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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
.tstest 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).
- Phase reported all gates passed
-
npx hardhat --versionruns and prints a3.xversion (e.g.3.9.0) - Checkpoint commit:
[CHECK] HH3 project setup: env, tsconfig, package.json
Phase 2 — Config → phase guide
Rewrites hardhat.config.ts to V3 declarative defineConfig (plugins, networks, custom tasks, solidity, verify, test settings).
- Phase reported all gates passed
- Checkpoint commit:
[CHECK] HH3 config: declarative defineConfig (solidity, networks, plugins, tasks, verify)
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).
-
npx hardhat test soliditypasses with zero errors (or skipped — no Solidity tests) - Checkpoint commit:
[CHECK] HH3 solidity test migration
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 reported all gates passed
-
npx tsc --noEmitpasses with zero errors -
npx hardhat test soliditystill passes (regression check — source changes can break Solidity tests) - Checkpoint commit:
[CHECK] HH3 source file migration: ESM conversion, V3 API updates, and TypeChain import fixes
Phase 5 — Test Fix-Up → phase guide
Gets the .ts test suite passing under V3.
-
npx tsc --noEmitstill passes with zero errors - Every test file passes individually (
npx hardhat test {file}) -
npx hardhat test soliditystill passes (regression check — test-helper/config fixes can break Solidity tests) - Checkpoint commit:
[CHECK] HH3 test suite fix-up: all tests 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.
- Phase reported all gates passed
-
npx tsc --noEmitstill passes with zero errors - Checkpoint commit:
[CHECK] HH3 script validation: all package.json scripts passing
Done
Stop and tell the user the migration is complete.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/nomicfoundation/hardhat-skills/migrate-hardhat2-to-hardhat3">View migrate-hardhat2-to-hardhat3 on skillZs</a>