Introducing OpenZeppelin Skills: Teaching AI Agents to Build Secure Smart Contracts

AI coding agents are writing smart contracts. The question is whether they're writing them securely.

When an AI agent generates a token contract, does it use the latest OpenZeppelin ERC-20 implementation or a version from its training data that may be two major releases behind, missing critical security updates? When it adds upgradeability, does it know that the transfer hook changed between Contracts v4 and v5 – a change that directly impacts security assumptions? When it implements access control, does it use battle-tested primitives or reinvent authentication from scratch?

Today we're open-sourcing OpenZeppelin Skills: agent skills that give AI coding assistants authoritative, up-to-date knowledge of the OpenZeppelin Contracts libraries. Instead of letting agents guess from stale training data, Skills provides the exact security patterns, APIs, and safety rules that power $35 trillion in onchain value transferred.

The Security Problem Skills Solves

AI coding agents have a training data problem that creates security risks. They know about OpenZeppelin Contracts, but they usually don't know the current OpenZeppelin Contracts, and that gap introduces vulnerabilities.

• Outdated security patterns: an agent might generate an ERC-20 with override points that existed in v4 but were removed in v5. The code compiles. It even looks right. But it doesn't behave correctly, and the security flaw is subtle enough to survive casual review.

• Reinvented security primitives: an agent asked to "add pausability" might write a custom paused modifier from scratch instead of importing Pausable, duplicating security logic that's been battle-tested across thousands of deployments and missing the security updates that come with using the audited library.

• Insecure toolchain setup: each blockchain ecosystem has its own project scaffolding, dependency management, and import conventions. Getting Foundry remappings wrong or declaring incorrect dependencies doesn't just waste time, but it can break verification workflows and make security review harder.

OpenZeppelin Skills eliminates these security risks by teaching agents to build with the same secure foundations trusted by the industry's most critical protocols.

What's Inside: 3 Security-Focused Skill Categories, 4 Languages

1. Develop Secure Contracts - The Core Skill

This is the security foundation. It enforces a single principle: prefer audited library components over custom code. The skill teaches agents a strict decision tree: search the library first, import and use if a match exists, extend only via designated override points, and write custom logic only as a last resort.

What makes this powerful for security:

The skill reads the user's existing project before suggesting changes, preventing agents from accidentally removing security controls when modifying code. It discovers integration patterns by reading the installed dependency source, not from memory, ensuring agents use the actual audited code in the project. And it includes MCP generator integration that works as a diff tool: generate a baseline, generate with a feature enabled, compare what changed, and apply only the delta to preserve existing security configurations.

It covers security-critical components: tokens (ERC-20, ERC-721, ERC-1155), access control (Ownable, AccessControl, AccessManager), security primitives (Pausable, ReentrancyGuard), governance, accounts, and more, across Solidity, Cairo, Stylus, and Stellar.

2. Setup Skills - Secure Project Scaffolding

Each ecosystem has its own toolchain, dependency format, and security gotchas. The setup skills encode the exact steps for secure configuration.

• Solidity covers Hardhat v2/v3 initialization, Foundry setup, @openzeppelin/contracts and upgradeable variant installation, and correct Foundry remappings, including the non-obvious pattern for upgradeable contracts where both import paths must resolve from the upgradeable submodule for Etherscan verification to work (critical for security transparency).

• Cairo handles Scarb + StarkNet Foundry scaffolding, umbrella vs. individual OpenZeppelin package selection (individual packages mean faster builds since you only compile what you use), correct import paths depending on which dependency style is declared, and component macro integration patterns that ensure security controls are properly initialized.

• Stylus covers the Rust nightly toolchain + WASM target, Cargo Stylus CLI, the openzeppelin-stylus crate with its export-abi feature flag, and Stylus-specific security patterns: #[storage] + #[entrypoint] struct declarations, #[public] + #[implements] dispatch registration.

• Stellar handles the Stellar CLI + Soroban WASM target, the workspace dependency structure (root Cargo.toml vs. per-contract), stellar-macros proc-macro attributes like #[when_not_paused], #[only_owner], and #[derive(Upgradeable)], plus platform-specific security guidance like TTL extension responsibility.

Without these skills, agents will attempt to set up projects from general knowledge and introduce configuration errors that compromise security review and verification workflows.

3. Upgrade Skills - Where Security Risk is Highest

Contract upgrades are the highest-stakes security operation in smart contract development. A storage layout mistake can corrupt the state of a contract holding millions in value. A missing access control check can allow unauthorized upgrades. Each blockchain environment handles upgrades differently, and the upgrade skills encode those security requirements precisely.

• Solidity uses proxy patterns (UUPS, Transparent, and Beacon) via EIP-1967. The skill prevents critical security issues: storage layout violations that corrupt state, missing initializer protection that allows reinitialization attacks, v4→v5 cross-version upgrades (namespaced storage is incompatible with sequential storage), forgetting _disableInitializers() in the constructor (which leaves initialization vulnerable), and incorrect ERC-7201 namespace computation that can cause storage collisions.

• Cairo uses replace_class_syscall, no proxies needed, the contract upgrades itself. The skill prevents critical security gaps: missing access control on upgrade functions (the OpenZeppelin component deliberately doesn't embed it, so developers must add their own, and forgetting this means anyone can upgrade the contract), storage key renames that silently corrupt state (slots are derived from variable names, not position), and cross-major-version storage incompatibility.

• Stylus uses the same EVM proxy patterns as Solidity, but implemented in Rust/WASM. The skill handles Stylus-specific security concerns: logic_flag context detection (since Stylus doesn't support immutable), mandatory WASM reactivation every 365 days (missing this bricks the contract), and correct VERSION_NUMBER management across upgrades to prevent storage corruption.

• Stellar uses native WASM bytecode replacement, no proxies, no delegatecall. The skill prevents the most catastrophic security failure: upgrading to a contract that doesn't include an upgrade mechanism, which permanently and irreversibly loses upgradeability and any ability to patch security vulnerabilities. It also covers atomic upgrade-and-migrate patterns (new code only executes after the current invocation completes, so an auxiliary Upgrader contract is needed) and storage key compatibility to prevent state corruption.

The Solidity upgrade skill alone is 14KB of detailed security guidance, covering Hardhat and Foundry plugin workflows, ERC-7201 storage location computation (with actual shell commands to generate the constants), the complete upgrade safety checklist, and the hierarchy for handling security validation issues.

Why This Matters for Blockchain Security

OpenZeppelin Skills operates at the foundation of the security stack. It's about building securely from the start, using the same audited standards that protect the industry's most critical deployments.

This distinction matters for security outcomes. An agent that uses audited library components correctly, configures projects securely, and handles upgrades safely produces code with fewer vulnerabilities from the start. Security through secure foundations, not just after-the-fact detection.

After securing $250B+ in onchain value across 900+ audits since 2016, we know what secure smart contract development looks like. OpenZeppelin Skills encodes that knowledge, teaching AI agents the same standards we've built and maintained for nearly a decade.

OpenZeppelin Skills are released under AGPL v3 and are available publicly on GitHub. The skills are maintained alongside the OpenZeppelin Contracts libraries they teach, and as the libraries evolve and receive security updates, the skills evolve with them.

Installation

Skills CLI:

npx skills add OpenZeppelin/openzeppelin-skills

Claude Code Plugin (also installs MCP servers for smart contract generation):

/plugin marketplace add OpenZeppelin/openzeppelin-skills
/plugin install openzeppelin-skills

Manual:

cp -r skills/*-contracts ~/.claude/skills/

MCP server documentation: mcp.openzeppelin.com