upgrade-solidity-contracts — Claude Code skill: overview
Guides Solidity smart contract upgrades using OpenZeppelin proxy patterns. It prevents storage layout bugs and shows how to set up ERC-7201 namespaced storage.
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a claude-codeWhat upgrade-solidity-contracts does
This skill guides coding agents through updating Solidity contracts via UUPS and Transparent proxies. It instructs models to replace constructors with functions guarded by the initializer modifier. Logic implementations get locked with _disableInitializers(). This step stops unauthorized setup calls.
Storage layout receives strict handling. The instructions forbid reordering, dropping, or mutating variable types. Instead, the rules favor ERC-7201 namespaced storage. Structs sit at deterministic slots, avoiding storage collisions without legacy storage gaps.
Upgrading an active proxy from OpenZeppelin Contracts v4 to v5 is impossible. You must deploy clean proxies instead. Because v4 relied on sequential slots, a v5 implementation cannot decode previously written state.
What it helps with
- convert contracts to UUPS or Beacon proxy patterns
- replace standard constructors with initializer logic
- configure state storage using the ERC-7201 standard
- validate storage layout compatibility before upgrades
Example prompts for the agent
- Refactor this token contract for UUPS and create an initialize function
- Check this new implementation storage layout for compatibility issues
- Help me move contract state variables into an ERC-7201 struct
How to install upgrade-solidity-contracts
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a claude-code2Manually: put the files in place
~/.claude/skills/upgrade-solidity-contracts/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/upgrade-solidity-contracts/
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a codex2Manually: put the files in place
.agents/skills/upgrade-solidity-contracts/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a cursor2Manually: put the files in place
.cursor/skills/upgrade-solidity-contracts/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install OpenZeppelin/openzeppelin-skills upgrade-solidity-contracts2Manually: put the files in place
.github/skills/upgrade-solidity-contracts/SKILL.md1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a gemini-cli2Platform CLI
gemini skills install https://github.com/OpenZeppelin/openzeppelin-skills --path skills/upgrade-solidity-contractsManually: put the files in place
.devin/skills/upgrade-solidity-contracts/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about upgrade-solidity-contracts
How to install upgrade-solidity-contracts in Claude Code?
Run npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a claude-code. This installs the skill files directly into your Claude Code setup.
What does upgrade-solidity-contracts do?
It gives your AI coding assistant specific guidelines for upgradeable smart contracts. It enforces OpenZeppelin proxy safety, initializer patterns, and storage integrity checks.
Can an existing proxy be upgraded from OpenZeppelin Contracts v4 to v5?
No, this upgrade path is not supported. Version 4 uses sequential slots while v5 uses namespaced storage, preventing the new implementation from reading past data.
