The Complete Production SOP: How to Deploy and Run OpenZeppelin Contracts Upgradability & Standards in Autonomous AI Agents
Step-by-step SOP to install and run OpenZeppelin Contracts Upgradability & Standards in Codex, Claude Code, & Cursor. Master UUPS proxies & access control.
Technical Overview & Architectural Context
Autonomous coding agents frequently introduce critical security vulnerabilities when drafting Web3 smart contracts. Left unconstrained, LLMs routinely implement outdated proxy mechanisms (such as unshielded delegatecall proxies), use regular constructors instead of OpenZeppelin's `Initializable` pattern, omit `_disableInitializers()` in implementation constructors, or inadvertently corrupt storage layouts by mutating variable ordering between contract upgrades. The `openzeppelin-contract-audit-standards` skill imposes deterministic operational guardrails across Codex, Claude Code, Cursor, and Windsurf. By enforcing strict adherence to official OpenZeppelin 5.x contracts, Universal Upgradeable Proxy Standards (UUPS), and explicit `AccessControl` patterns, this skill forces the agent to execute compile-time storage layout checks, avoid anti-patterns, and validate state changes against production security checklists prior to file delivery.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent runtime.
Agent runtimes such as Claude Code and Cursor scan local hidden directories (`.claude/skills/`, `.cursor/rules/`, or generic `.agents/skills/`) to parse triggers and bounded tool capabilities. We install the official `SKILL.md` file so the agent automatically binds to upgradeability validation prompts.
mkdir -p .agents/skills/openzeppelin-contract-audit-standards && curl -fsSL https://askills.dev/api/skills/openzeppelin-contract-audit-standards/raw -o .agents/skills/openzeppelin-contract-audit-standards/SKILL.md---
name: "openzeppelin-contract-audit-standards"
description: "Implement audited, industry-standard ERC token standards and proxy upgrade patterns."
metadata:
author: "OpenZeppelin"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "use openzeppelin contracts"
- "implement uups upgradeable proxy"
- "setup accesscontrol roles"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# OpenZeppelin Contracts Upgradability & Standards SOP
1. Always import from `@openzeppelin/contracts-upgradeable` when deploying proxy architectures.
2. Add `/// @custom:oz-upgrades-unsafe-allow constructor` and call `_disableInitializers();` in implementation constructors.
3. Implement `_authorizeUpgrade(address newImplementation)` protected strictly with `onlyRole(UPGRADER_ROLE)`.
4. Prohibit custom delegatecall routing or raw slot writes outside OpenZeppelin standard storage abstractions.Place the SKILL.md file directly within your root repository under `.agents/skills/` to prevent LLMs from wasting context tokens querying external web documentation.
Ensure `shell_exec: false` remains respected by runtime sandboxes; do not grant root shell execution to agents when compiling untrusted third-party dependencies.
Environment Secrets & Dependency Validation
Install verified OpenZeppelin dependencies and initialize configuration without exposing private keys.
Autonomous agents often pull incompatible versions of OpenZeppelin (e.g., mixing v4 legacy patterns with v5 namespaces). We run deterministic dependency commands to ensure Foundry and NPM workspace dependencies match the upgradeable target specification.
forge install OpenZeppelin/openzeppelin-contracts --no-commit && forge install OpenZeppelin/openzeppelin-contracts-upgradeable --no-commit && npm install --save-dev @openzeppelin/hardhat-upgradesRun `forge remappings` to map `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/` cleanly inside `remappings.txt`.
Never place contract deployer private keys directly inside agent prompts or uncommitted `.env` files accessible to LLM session logs.
Intent Matching & Trigger Invocation
Invoke deterministic contract creation using verified trigger keywords.
Execute task instructions utilizing designated frontmatter triggers like 'implement uups upgradeable proxy' to switch the agent into strict OpenZeppelin validation mode.
claude "implement uups upgradeable proxy for a capped ERC20 token with accesscontrol roles"Mention the explicit trigger phrase verbatim in the first sentence of your prompt to force priority indexing in Codex and Claude Code runtimes.
Ambiguous commands like 'write a generic upgradeable token' may bypass skill triggers and result in non-standard, vulnerable proxy code.
Storage Layout Verification & Quality Gate
Execute automated self-healing checks and storage layout diffing before accepting agent deliverables.
Before marking the task complete, the skill mandates that the agent verify contract compilation and run OpenZeppelin storage layout validation tests to guarantee backwards compatibility.
forge build --extra-output storageLayout && npx hardhat checkCheck `git diff --stat` before confirming the agent's pull request to verify no unexpected storage variables were moved or retyped.
Failing to check storage layout output can cause irreversible storage collision when migrating state variables on-chain.
Real-World Scenario: Build a Production-Ready UUPS Upgradeable ERC20 Token with Role-Based Access Control
“implement uups upgradeable proxy for our governance token GovToken.sol. It must inherit ERC20Upgradeable, ERC20PermitUpgradeable, and AccessControlUpgradeable. Only addresses with UPGRADER_ROLE can authorize upgrades, and MINTER_ROLE can mint new tokens up to 100M cap.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent declared initial field values (e.g., `uint256 public cap = 100_000_000 * 1e18;`) inline or within a standard constructor instead of inside the `initialize` method.
Remove inline initialization in state variable declarations and move logic into `function initialize(...) initializer public { __ERC20_init(...); __AccessControl_init(); }` with an empty implementation constructor that calls `_disableInitializers();`.Root Cause: The agent reordered existing state variables or inserted a new state variable ahead of existing declarations, mutating storage slots.
Revert the variable ordering in `contracts/GovTokenV2.sol`. Always append new storage variables to the end of the contract or use ERC-7201 namespaced storage patterns: `forge clean && forge build --extra-output storageLayout`.Frequently Asked Questions (OpenZeppelin Contracts Upgradability & Standards SOP)
Q:Can I use OpenZeppelin Contracts Upgradability & Standards across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification supported across all modern agent runtimes. Simply symlink or copy `.agents/skills/openzeppelin-contract-audit-standards/SKILL.md` into your project root or Claude Code skill directory.
Q:How does OpenZeppelin Contracts Upgradability & Standards prevent context window overflow during long agent sessions?
By establishing concise procedural boundaries and deterministic validation gates rather than polluting system prompts with redundant rules. It supplies tight patterns for UUPS proxies and AccessControl rather than full raw source libraries.
Q:Does this skill require escalated root or container permissions?
No. It is audited with a security score of 98/100 and runs safely within workspace-scoped sandboxes with read and workspace-write permissions only (`fs_read: true`, `fs_write: 'workspace'`, `shell_exec: false`).
Ready to equip your autonomous agent with OpenZeppelin Contracts Upgradability & Standards?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.