# upgrade-cairo-contracts

upgrade-cairo-contracts is a Claude Code skill that explains Starknet class replacement with OpenZeppelin’s UpgradeableComponent. It covers access checks and upgrade tests.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 234 installs · ★ 225 repo stars
- 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-cairo-contracts/SKILL.md
- Updated: 2026-10-19
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/upgrade-cairo-contracts

## What it does

On Starknet, an upgrade points a contract instance to a different class while its address and stored state remain in place. The skill covers `replace_class_syscall` and wiring in `UpgradeableComponent`, which validates the class hash and emits an `Upgraded` event. It also describes `IUpgradeAndCall` for running a function in the new class after the swap.

The external upgrade entry point needs its own authorization check; the component does not supply one. Without that guard, any caller can change the contract’s code. Storage names and types matter: renaming an existing variable or changing its type can make old state inaccessible. Cairo has no automated storage-layout validation, so test the transition in a devnet.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

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

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-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-cairo-contracts/SKILL.md

## When to use it
- point a Starknet contract at a new class
- add an authorization check to the upgrade entry point
- preserve access to existing contract state
- test state reads and permissions after an upgrade
- compare Starknet class replacement with EVM proxy upgrades

## Example prompts
- Explain how to upgrade my Cairo contract with `replace_class_syscall` and `UpgradeableComponent`.
- Review my contract’s upgrade function and show how to restrict who can call it.
- Plan a V1-to-V2 devnet test that checks storage compatibility and access control.

## Similar
- [OpenZeppelin Cairo Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-cairo-contracts.md) — MCP server
- [cairo-vulnerability-scanner](https://affpapa.org/en/nevibecode/skills/cairo-vulnerability-scanner.md) — skill · 5700 installs
- [ethereum](https://affpapa.org/en/nevibecode/skills/ethereum.md) — skill · 783 installs
- [OpenZeppelin Solidity Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-solidity-contracts.md) — MCP server
- [solidity-hardhat-cursorrules-prompt-file](https://affpapa.org/en/nevibecode/rules/solidity-hardhat-cursorrules-prompt-file.md) — rule · ★ 41178 repo stars
- [OpenZeppelin Stylus Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-stylus-contracts.md) — MCP server

From the same set: [openzeppelin/openzeppelin-skills](https://affpapa.org/en/nevibecode/by/openzeppelin/openzeppelin-skills.md) — 5 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
