# upgrade-solidity-contracts

Guides Solidity smart contract upgrades using OpenZeppelin proxy patterns. It prevents storage layout bugs and shows how to set up ERC-7201 namespaced storage.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 472 installs · ★ 219
- Author: OpenZeppelin
- License: AGPL-3.0-only · policy=link-only · description only; the file stays with the author
- Source: https://github.com/OpenZeppelin/openzeppelin-skills/tree/HEAD/skills/upgrade-solidity-contracts/SKILL.md
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/skills/upgrade-solidity-contracts

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/upgrade-solidity-contracts/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/upgrade-solidity-contracts/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/upgrade-solidity-contracts/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/upgrade-solidity-contracts/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install OpenZeppelin/openzeppelin-skills upgrade-solidity-contracts
```

2. **Manually: put the files in place**
- File: `.github/skills/upgrade-solidity-contracts/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/OpenZeppelin/openzeppelin-skills --path skills/upgrade-solidity-contracts
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/upgrade-solidity-contracts/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-solidity-contracts -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/OpenZeppelin/openzeppelin-skills/tree/HEAD/skills/upgrade-solidity-contracts/SKILL.md

## When to use it
- 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
- 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

## Similar
- [solidity-hardhat-cursorrules-prompt-file](https://affpapa.org/en/nevibecode/rules/solidity-hardhat-cursorrules-prompt-file.md) — rule · ★ 41011
- [ethereum](https://affpapa.org/en/nevibecode/skills/ethereum.md) — skill · 737 installs
- [solidity](https://affpapa.org/en/nevibecode/rules/solidity.md) — rule · ★ 3579
- [solidity-auditor](https://affpapa.org/en/nevibecode/skills/solidity-auditor.md) — skill · 830 installs
- [solidity-gas-optimization](https://affpapa.org/en/nevibecode/skills/solidity-gas-optimization.md) — skill · 547 installs
- [solidity-security](https://affpapa.org/en/nevibecode/skills/solidity-security.md) — skill · 15382 installs

From the same set: [openzeppelin/openzeppelin-skills](https://affpapa.org/en/nevibecode/by/openzeppelin/openzeppelin-skills.md) — 2 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md