# upgrade-stylus-contracts

upgrade-stylus-contracts guides assistants through building upgradeable Arbitrum Stylus Rust contracts using OpenZeppelin proxy patterns.

- 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-stylus-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-stylus-contracts

## What it does

This skill guides the agent through architecting upgradeable Stylus programs written in Rust. Because Stylus runs as WebAssembly within the EVM state structure on Arbitrum, standard proxy patterns like UUPS and Beacon work similarly to Solidity. The instructions outline slot layout rules with the `#[storage]` macro, initialization flows, and proxy integration.

Stylus lacks `immutable` state variables. Instead of checking a cached implementation address, the contract manages execution context with a dedicated boolean `logic_flag`. The implementation constructor marks this flag in its personal storage, allowing `only_proxy()` to detect direct executions and block unproxied upgrades.

WASM programs on Arbitrum mandate reactivation every 365 days or following network runtime updates. Access restriction is omitted from core upgrade handlers by default, meaning developers must safeguard `upgrade_to_and_call` themselves.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

2. **Manually: put the files in place**
- File: `.cursor/skills/upgrade-stylus-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-stylus-contracts
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

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

## When to use it
- implement UUPS upgradeability inside an Arbitrum Stylus Rust program
- verify memory layout safety before rolling out contract revisions
- deploy a Beacon proxy setup for coordinated multi-contract upgrades
- secure the `upgrade_to_and_call` handler with ownership checks

## Example prompts
- Set up UUPSUpgradeable for this Stylus contract with Ownable permissions
- Check my #[storage] layout to ensure compatibility with the previous release
- Generate the initialization code for an Erc1967Proxy targeting a Stylus program

## Similar
- [OpenZeppelin Stylus Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-stylus-contracts.md) — MCP server
- [OpenZeppelin Solidity Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-solidity-contracts.md) — MCP server
- [ethereum](https://affpapa.org/en/nevibecode/skills/ethereum.md) — skill · 783 installs
- [OpenZeppelin Cairo Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-cairo-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 Stellar Contracts](https://affpapa.org/en/nevibecode/mcp/openzeppelin-stellar-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
