Solidity Agent Skills

Curated Solidity best practices for AI coding agents (Cursor, Codex, Claude Code).

Skills are packaged instructions that help AI coding agents write better, more secure, and gas-efficient Solidity code.

Available Skills

| Skill | Description | |-------|-------------| | solidity-style | Code style, formatting, and design patterns | | solidity-security | Security patterns and vulnerability prevention | | solidity-gas | Gas optimization techniques |

Installation

Quick Install (npx)

npx solidity-agent-skills

This launches an interactive installer that lets you:

1. Select which skills to install
2. Choose target agents (Cursor, Codex, Claude Code)
3. Install to project or global scope

Manual Installation

Copy the desired SKILL.md files to your agent's config directory:

Cursor:

mkdir -p .cursor/rules
cp skills/solidity-style/SKILL.md .cursor/rules/solidity-style.md

Claude Code:

mkdir -p .claude
cp skills/solidity-style/SKILL.md .claude/solidity-style.md

Codex:

mkdir -p .codex
cp skills/solidity-style/SKILL.md .codex/solidity-style.md

Usage

Once installed, skills are automatically available to your AI coding agent. The agent will apply the relevant best practices when:

• Writing new Solidity contracts
• Reviewing existing code
• Implementing specific patterns (upgrades, access control, etc.)
• Optimizing for gas

Example Prompts

"Create an ERC20 token with minting capability"

The agent will apply:

• Style conventions (naming, imports, NatSpec)
• Security patterns (access control, SafeERC20)
• Gas optimizations (immutable, packed storage)

"Review this contract for security issues"

The agent will check for:

• Reentrancy vulnerabilities
• Access control issues
• Input validation
• CEI pattern compliance

Skills Overview

solidity-style

Covers coding conventions and design patterns from:

• Solidity Style Guide
• OpenZeppelin Guidelines
• Taiko Protocol Conventions

Key topics:

• Named imports and code organization
• Naming conventions (underscore prefixes, param/return naming)
• Function ordering and visibility
• NatSpec documentation
• Custom errors and events
• UUPS upgradeable patterns
• Storage gaps and upgrade safety
• Access control patterns

solidity-security

Covers security best practices from:

• Solidity Security Considerations
• RareSkills Smart Contract Security
• Common Beginner Mistakes

Key topics:

• Checks-Effects-Interactions (CEI) pattern
• Reentrancy prevention
• Access control
• Input validation
• SafeERC20 usage
• Flash loan awareness

solidity-gas

Covers optimization techniques from:

• RareSkills Gas Optimization
• Production rollup contract patterns

Key topics:

• Storage optimization (packing, caching, zero→non-zero)
• Immutable/constant usage
• Loop optimization
• Custom errors vs require strings
• Calldata vs memory
• L1 vs L2 considerations

Solodit API Integration (Optional)

The solidity-security skill includes integration with Cyfrin Solodit, a database of 49,000+ real-world smart contract vulnerabilities from professional audits.

What It Enables

When configured, AI agents can search the vulnerability database during security reviews to find similar issues from past audits, enhancing manual review with real-world findings.

Setup

1. Get an API key (free):

   • Go to solodit.cyfrin.io
   • Sign in or create an account
   • Click profile dropdown → "API Keys"
   • Create a new key

2. Set the environment variable:

   # Add to ~/.bashrc, ~/.zshrc, or equivalent:
   export SOLODIT_API_KEY="sk_your_key_here"

3. Reload your shell:

   source ~/.bashrc  # or ~/.zshrc

Without API Key

Skills work fully without the API key. The security skill will:

• Inform you that enhanced search is available
• Continue with comprehensive manual review
• Apply all patterns and checklists from the skill

See skills/solidity-security/references/solodit-api.md for full API documentation.

Development

Local Testing

The npx solidity-agent-skills command requires the package to be published to npm. For local development and testing, use one of these methods:

Option 1: Direct execution

# Run the installer directly from the project directory
node bin/add-skill.js

# Or use npx with a local path
npx /path/to/solidity-agent-skills

Option 2: npm link

# From the project root, create a global symlink
npm link

# Now you can run the command globally
solidity-agent-skills

# To unlink when done
npm unlink -g solidity-agent-skills

Dev Mode

When developing the installer itself:

# Run with Node directly to see full error output
node bin/add-skill.js

# Or with the --help flag to verify CLI setup
node bin/add-skill.js --help

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Update or add skills (ensure accuracy and test examples)
4. Submit a pull request with a clear description

Skill Format

Each skill follows the Agent Skills format:

skills/
└── skill-name/
    ├── SKILL.md          # Main instructions (with YAML frontmatter)
    └── references/       # Supporting docs (optional)

Quality Guidelines

• All code examples should be syntactically correct
• Include both ✅ good and ❌ bad examples where helpful
• Keep explanations concise but complete
• Test that patterns work with current Solidity versions (0.8.x)

Project Structure

solidity-agent-skills/
├── bin/
│   └── add-skill.js      # CLI installer
├── skills/
│   ├── solidity-style/   # Style and patterns skill
│   ├── solidity-security/# Security skill
│   └── solidity-gas/     # Gas optimization skill
├── package.json
└── README.md

License

MIT