Upgrade Solidity Contracts
If you're working with OpenZeppelin proxy patterns, this walks you through UUPS, Transparent, and Beacon upgrades with the context you actually need. It covers the v4 to v5 migration gotcha (namespaced storage means you can't upgrade across major versions), shows you how to write initializers instead of constructors, and explains ERC-7201 namespaced storage with the actual formula for computing storage locations. The Hardhat and Foundry workflows are both documented, and there's a solid breakdown of when each proxy pattern makes sense. Honest take: the upgrade restrictions section alone will save you from a painful mistake if you're maintaining older contracts.
- skills.sh installs
- 500
- GitHub stars
- 222
- last updated
- Aug 21, 2026
Install
$ npx -y skills add openzeppelin/openzeppelin-skills --skill upgrade-solidity-contracts --agent claude-codeInstalls into .claude/skills of the current project.
Files
Solidity Upgrades
Contents
- Proxy Patterns Overview
- Upgrade Restrictions Between Major Versions (v4 → v5)
- Writing Upgradeable Contracts
- Hardhat Upgrades Workflow
- Foundry Upgrades Workflow
- Handling Upgrade Validation Issues
- Upgrade Safety Checklist
Proxy Patterns Overview
| Pattern | Upgrade logic lives in | Best for |
|---|---|---|
UUPS (UUPSUpgradeable) | Implementation contract (override _authorizeUpgrade) | Most projects — lighter proxy, lower deploy gas |
| Transparent | Separate ProxyAdmin contract | When admin/user call separation is critical — admin cannot accidentally call implementation functions |
| Beacon | Shared beacon contract | Multiple proxies sharing one implementation — upgrading the beacon atomically upgrades all proxies |
All three use EIP-1967 storage slots for the implementation address, admin, and beacon.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageDetails
- Repository
- github.com/openzeppelin/openzeppelin-skills
- Categories
- Frontend Development, Backend & APIs, Web3 & Blockchain
- First seen
- Jun 3, 2026
More from openzeppelin/openzeppelin-skills
All 5Recommended
More Frontend Development
canghe-post-to-wechatfreestylefly/canghe-skillsPosts content to WeChat Official Account (微信公众号) via API or Chrome CDP. Supports article posting (文章) with HTML, markdown, or plain text input, and image-text p498skills.sh installs
safe-action-better-authnext-safe-action/skillsUse when adding authentication or authorization to safe actions with Better Auth -- covers betterAuth() middleware setup, typed session context (BetterAuthConte496skills.sh installs
coding-standardsdavila7/claude-code-templatesUniversal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.494skills.sh installs
helpparcadei/continuous-claude-v3Interactive workspace discovery - learn what tools, workflows, agents, and hooks are available493skills.sh installsautonomous-agentsdavila7/claude-code-templatesAutonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The chal492skills.sh installs
pdf-generationglebis/claude-skillsProfessional PDF generation from markdown using Pandoc with Eisvogel template and EB Garamond fonts. Use when converting markdown to PDF, creating white papers,489skills.sh installs