upgrade-cairo-contracts — Claude Code skill for Cairo upgrades
upgrade-cairo-contracts is a Claude Code skill that explains Starknet class replacement with OpenZeppelin’s UpgradeableComponent. It covers access checks and upgrade tests.
AGPL-3.0-only 234 installs ★ 225 updated 2026-10-19
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-contracts -a claude-codeWhat upgrade-cairo-contracts 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.
What it helps with
- 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 for the agent
- Explain how to upgrade my Cairo contract with
replace_class_syscallandUpgradeableComponent. - 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.
How to install upgrade-cairo-contracts
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-contracts -a claude-code2Manually: put the files in place
~/.claude/skills/upgrade-cairo-contracts/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/upgrade-cairo-contracts/
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-contracts -a codex2Manually: put the files in place
.agents/skills/upgrade-cairo-contracts/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-contracts -a cursor2Manually: put the files in place
.cursor/skills/upgrade-cairo-contracts/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install OpenZeppelin/openzeppelin-skills skills/upgrade-cairo-contracts2Manually: put the files in place
.github/skills/upgrade-cairo-contracts/SKILL.md1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-contracts -a gemini-cli2Platform CLI
gemini skills install https://github.com/OpenZeppelin/openzeppelin-skills --path skills/upgrade-cairo-contractsManually: put the files in place
.devin/skills/upgrade-cairo-contracts/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-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-cairo-contracts
How do I install upgrade-cairo-contracts in Claude Code?
Run npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-cairo-contracts -a claude-code. The skill file is placed at ~/.claude/skills/upgrade-cairo-contracts/SKILL.md.
What does upgrade-cairo-contracts do?
It guides Cairo contract upgrades on Starknet, covering class replacement, OpenZeppelin’s UpgradeableComponent, access checks, and storage compatibility.
Why does the upgrade function need a separate access check?
UpgradeableComponent does not enforce permissions. Without a guard on the external function, any caller could replace the contract’s code.