upgrade-stellar-contracts — Claude Code skill
upgrade-stellar-contracts — a skill for upgrading Stellar/Soroban smart contracts with OpenZeppelin's upgradeable module. Use it to make contracts updatable, migrate storage data, or ensure compatibility across bytecode replacements.
AGPL-3.0-only 281 installs ★ 225 updated 2026-10-19
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-codeWhat upgrade-stellar-contracts does
Soroban lets contracts upgrade their own WASM code through a protocol-level mechanism—no proxy contracts needed. The skill provides two patterns: Upgradeable for code-only updates and UpgradeableMigratable when storage must change too. Derive macros automatically set the version from Cargo.toml into WASM metadata per SEP-49.
For atomic upgrade-and-migrate in a single call, wrap both operations in an auxiliary Upgrader contract. When bytecode is replaced, the new contract's constructor does not run; initialization must happen via migration. Storage keys must remain stable—removing, renaming, or changing their types will corrupt state.
Authorization lives in your _require_auth implementation. Skipping this check exposes the contract to unauthorized code replacement. Leverage Ownable for single-owner access or AccessControl from the access package for role-based control.
What it helps with
- make a Soroban contract updatable without a proxy pattern
- migrate storage data during a contract upgrade
- perform code upgrade and storage migration in one atomic transaction
- maintain storage key compatibility across versions
- test upgrade scenarios for Soroban contracts
Example prompts for the agent
- Add
#[derive(Upgradeable)]to your contract struct and implement authorization in_require_auth - Use
UpgradeableMigratableto transform data during upgrade via the_migratemethod - Wrap upgrade and migration in an
Upgradercontract to execute them atomically
How to install upgrade-stellar-contracts
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-code2Manually: put the files in place
~/.claude/skills/upgrade-stellar-contracts/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/upgrade-stellar-contracts/
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a codex2Manually: put the files in place
.agents/skills/upgrade-stellar-contracts/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a cursor2Manually: put the files in place
.cursor/skills/upgrade-stellar-contracts/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install OpenZeppelin/openzeppelin-skills skills/upgrade-stellar-contracts2Manually: put the files in place
.github/skills/upgrade-stellar-contracts/SKILL.md1Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a gemini-cli2Platform CLI
gemini skills install https://github.com/OpenZeppelin/openzeppelin-skills --path skills/upgrade-stellar-contractsManually: put the files in place
.devin/skills/upgrade-stellar-contracts/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-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-stellar-contracts
How do I install upgrade-stellar-contracts in Claude Code?
Run npx skills add OpenZeppelin/openzeppelin-skills --skill upgrade-stellar-contracts -a claude-code, then open ~/.claude/skills/upgrade-stellar-contracts/SKILL.md.
What does the upgrade-stellar-contracts skill do?
It simplifies Soroban contract updates. It provides derive macros for code-only upgrades, storage migration, and atomic upgrade-with-migration patterns in a single invocation.
When should I use Upgradeable vs. UpgradeableMigratable?
Use Upgradeable if you only need to replace the bytecode. Use UpgradeableMigratable if you must also transform data stored in the contract during the upgrade.