AI 編碼智能體為何會在 EVM 問題上產生幻覺，以及 Spellbook Skills 如何封裝 5 項可測試技能

If you have tried using Claude Code, Cursor, or ChatGPT to debug a reverting Solidity transaction or write Foundry invariants, you have probably watched this sequence play out:

1. You feed the agent an error message or a raw transaction hash.
2. The model apologizes, guesses three different reasons why the call might have failed, and suggests rewriting a functioning helper contract.
3. If you ask it to generate an invariant test, it hallucinates a stateless property or creates a ghost variable that passes without ever touching real contract storage.

The problem isn't that current LLMs lack Solidity knowledge. The problem is that general-purpose coding agents lack a repeatable, evidence-first workflow for Web3 systems.

In Web3, a wrong suggestion isn't just a syntax error that fails the build. It can mean an unhandled reorg, an unauthorized external call, or a misconfigured slippage parameter.

To fix this, we structured and open-sourced Spellbook Skills: five testable, deterministic workflow packs designed for AI coding agents like Claude Code, Cursor, and Antigravity.

Here is why coding agents fail on EVM tasks, how structured skills change their behavior, and how you can install them today.

The Core Problem: Reasoning Without Evidence

When a human smart contract engineer investigates a revert, they follow a systematic loop:

Get tx receipt → Decode custom error selector → Pull trace via `cast run` → Inspect storage slot / state → Form hypothesis → Write reproducible test

When an unguided AI agent tries to do the same task, it skips directly from raw error → proposed code edit. It relies on pattern-matching against training data rather than verifying the actual state on-chain.

To make an agent reliable, you don't need a larger prompt. You need to constrain the agent with four operational boundaries:

1. Evidence before conclusions: The agent must pull the revert reason or cast run trace before suggesting code modifications.
2. Strict separation of roles: Scaffolding a test is different from verifying a vulnerability.
3. Zero secret handling: An agent must never ask for, log, or accept private keys, mnemonic phrases, or live signer credentials.
4. Deny-by-default execution: Any on-chain action or transaction proposal must pass an explicit policy gate before it can be executed.

The 5 Skills We Packaged

Rather than building a monolithic "all-in-one Web3 agent," we built five focused skills. Each skill contains a SKILL.md operating specification, reference check-lists, test fixtures, and runnable helpers.

1. evm-tx-failure-diagnoser

What it targets: Cryptic reverts, custom error selectors, gas exhaustion, and nonce collisions.

The workflow: It prevents the agent from guessing. The agent is forced to decode the 4-byte error selector, fetch the trace via cast run <TX_HASH> or local RPC, isolate the failing call frame, and document the root cause before touching contract files.

2. foundry-invariant-scaffold

What it targets: Brittle unit tests that miss edge-case multi-step exploits.

The workflow: Guides the agent through setting up genuine stateful fuzzing in Foundry. It scaffolds dedicated handler contracts, defines actor proxies, bounds inputs with realistic ghost variables, and structures assertions that check system-level invariants across sequences of calls.

3. web3-agent-tx-safety

What it targets: Autonomous agents that propose or broadcast transactions.

The workflow: Implements a strict, deny-by-default transaction policy gate. Every transaction payload must pass through parameter bounds (target allowlist, max value, calldata selector inspection) and a simulated dry-run before any signing payload can be constructed.

4. slither-finding-verifier

What it targets: Static analysis triage fatigue and false positives.

The workflow: Takes raw Slither JSON output and normalizes it into a triage worksheet. It requires the agent to verify the finding against actual source AST before generating a targeted, reproducible test case that confirms whether the vulnerability is exploitable or benign.

5. rpc-event-reliability

What it targets: Event listeners that miss logs during network congestion or reorgs.

The workflow: Hardens log ingestion backends. It structures durable event deduplication keys (chain + blockHash + txHash + logIndex), configures Viem fallback transports, and builds reorg reconciliation routines that handle chain reorganizations gracefully.

How to Install and Use Them

All five skills are open-source under the MIT License.

If you use the skills CLI, you can install any of them directly into your agent's workspace:

# Install the EVM Diagnoser for Claude Code
npx skills add theweb3wizard/spellbook-skills --skill evm-tx-failure-diagnoser -a claude-code

# Install the Foundry Invariant Scaffolder
npx skills add theweb3wizard/spellbook-skills --skill foundry-invariant-scaffold -a claude-code

# Or install all 5 skills into your project
npx skills add theweb3wizard/spellbook-skills --skill '*' -a claude-code

Manual Installation

You can also clone the repository and drop the skill directories directly into your workspace:

• Claude Code: .claude/skills/<skill-name>/
• Cursor / Codex: .agents/skills/<skill-name>/

git clone https://github.com/theweb3wizard/spellbook-skills.git

Example: What a Guarded Agent Run Looks Like

Here is what happens when you prompt an agent equipped with evm-tx-failure-diagnoser:

Prompt:

"Our deposit transaction reverted on Base: 0x7a8b...3f1c. Figure out why and tell me what needs fixing."

Without the skill:
The agent often guesses: "It looks like you didn't approve the ERC20 token first, or the contract is paused."

With the skill:
The agent executes the diagnostic workflow:

1. It queries the transaction receipt and extracts the revert data: 0x118cdaa7.
2. It decodes the selector against the project ABI: InsufficientCollateral(uint256 current, uint256 required).
3. It notes that the required collateral threshold was calculated using an oracle timestamp older than the protocol's staleness tolerance (maxOracleDelay = 3600).
4. It outputs an evidence-backed triage report and suggests a regression test fixture rather than blindly editing contract code.

Open Source & Community Feedback

We built these skills as part of our work at Spellbook, where we design and deploy production-ready AI agents for Web3 protocols.

The skills are completely free and testable offline. You can review the full code, test suites, and workflows here:

• 🐙 GitHub Repository: github.com/theweb3wizard/spellbook-skills
• 📖 Interactive Skills Directory: spellbook.theweb3wizard.xyz/skills

If you test them out on your smart contract projects, drop a reaction or let me know what other recurring Web3 workflows your agents struggle with in the comments below!