Agent skill

Smart Contract Reading Guide

by nirholas in nirholas/three.ws

How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns.

MITAuto-check passedBackend & APIs

Install Smart Contract Reading Guide

skills CLI
$ npx skills add nirholas/three.ws --skill smart-contract-reading-guide -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install nirholas/three.ws smart-contract-reading-guide --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/nirholas/three.ws.git skills-src && mkdir -p .claude/skills && cp -r skills-src/data/skills/development/smart-contract-reading-guide .claude/skills/smart-contract-reading-guide && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
smart-contract-reading-guide
GitHub stars
226
Token cost
~2.1k tokens
SKILL.md length
697 words
Files
1
Skills in repo
165
Repo updated
First seen
Licence
MIT

At a glance

How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns.

  • Works in 4 steps: Go to the explorer → Enter contract… → Click "Contract" tab → Look for the green checkmark ("Contract… → …
  • Helping users verify contracts
  • SKILL.md covers Finding Contract Code, Understanding Contract Structure, Reading on Etherscan and Decoding Transactions, plus 6 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Smart Contract Reading Guide is an agent skill from nirholas/three.ws. How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns. Use when helping users verify contracts, understand DeFi protocol mechanics, or decode on-chain activity.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Smart contracts and Crypto and DeFi analysis. It works with Solidity. The repository describes itself as: Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web… The licence is MIT.

When your agent uses it

  • Helping users verify contracts
  • Understand DeFi protocol mechanics
  • Decode on-chain activity

Example prompts

  • “/smart-contract-reading-guide”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Go to the explorer → Enter contract address
  2. Click "Contract" tab
  3. Look for the green checkmark ("Contract Source Code Verified")
  4. If not verified → RED FLAG — don't interact with unverified contracts

What it can do on your machine

Read from SKILL.md and the folder at commit 238ef60. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are solidity and json).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • etherscan.io
    • arbiscan.io
    • docs.soliditylang.org
    • openzeppelin.com
    • docs.chat.sperax.io

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Smart Contract Reading Guide loads about 2.1k tokens when it runs. Until then it costs about 74 tokens; SKILL.md has 697 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~74
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from nirholas/three.ws at commit 238ef60, republished under its MIT licence (© nirholas). 697 words, ~2,121 tokens.

Download SKILL.mdSave it as .claude/skills/smart-contract-reading-guide/SKILL.md (or your agent's skills folder).
name
smart-contract-reading-guide
description
How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns. Use when helping users verify contracts, understand DeFi protocol mechanics, or decode on-chain activity.
license
MIT
metadata.category
development
metadata.difficulty
advanced
metadata.author
clawhub
metadata.tags
development, smart-contract-reading-guide

Smart Contract Reading Guide

You don't need to be a Solidity developer to read smart contracts. This guide teaches you to understand what contracts do by reading their code on block explorers.

Finding Contract Code

Block Explorers
ChainExplorerURL
EthereumEtherscanetherscan.io
ArbitrumArbiscanarbiscan.io
BaseBaseScanbasescan.org
OptimismOptimistic Etherscanoptimistic.etherscan.io
PolygonPolygonScanpolygonscan.com
Steps to Read a Contract
  1. Go to the explorer → Enter contract address
  2. Click "Contract" tab
  3. Look for the green checkmark ("Contract Source Code Verified")
  4. If not verified → RED FLAG — don't interact with unverified contracts

Understanding Contract Structure

Solidity 101 for Readers
solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

// Interface — defines what functions exist
interface IERC20 {
    function transfer(address to, uint256 amount) external returns (bool);
    function balanceOf(address account) external view returns (uint256);
}

// Contract — the actual code
contract MyToken is IERC20 {
    // State variables (stored on blockchain)
    string public name = "My Token";
    mapping(address => uint256) private _balances;
    address public owner;
    
    // Events (logs, used for tracking)
    event Transfer(address indexed from, address indexed to, uint256 value);
    
    // Modifier (access control)
    modifier onlyOwner() {
        require(msg.sender == owner, "Not owner");
        _;
    }
    
    // View function (read-only, free to call)
    function balanceOf(address account) external view returns (uint256) {
        return _balances[account];
    }
    
    // State-changing function (costs gas)
    function transfer(address to, uint256 amount) external returns (bool) {
        _balances[msg.sender] -= amount;
        _balances[to] += amount;
        emit Transfer(msg.sender, to, amount);
        return true;
    }
    
    // Owner-only function (⚠️ check these carefully)
    function mint(address to, uint256 amount) external onlyOwner {
        _balances[to] += amount;
    }
}
Key Solidity Concepts
ConceptMeaningWhy It Matters
publicAnyone can call/readNormal, expected
externalOnly callable from outsideNormal for functions
view / pureRead-only (free to call)Safe — no state changes
onlyOwnerOnly the owner can callCheck what owner can do
payableCan receive ETHMay collect fees
mappingKey-value storageStores balances, approvals
requireValidation checkIf false, transaction reverts
emitLogs an eventUsed for tracking

Reading on Etherscan

"Read Contract" Tab

Free queries — anyone can call these:

FunctionWhat It Returns
name()Token name
symbol()Token symbol (e.g., "USDC")
decimals()Decimal places (6 for USDC, 18 for most tokens)
totalSupply()Total tokens in existence
balanceOf(address)How many tokens an address holds
owner()Who controls the contract
paused()Whether the contract is paused
"Write Contract" Tab

Requires wallet connection and gas:

FunctionWhat It DoesRisk Level
transfer()Send tokensNormal
approve()Grant spending permissionMedium (check amount)
stake()Lock tokens for rewardsNormal
mint()Create new tokensCheck who can call

Decoding Transactions

Transaction Overview

On any transaction page:

FieldWhat It Shows
StatusSuccess or Failed
FromSender address
ToContract called
ValueETH sent
Input DataFunction call + parameters
Gas UsedActual gas consumed
Reading Input Data

Raw input data looks like:

0xa9059cbb000000000000000000000000abcdef...00000000000000000000000000000000000000000000000000000002540be400

Decoded (Etherscan does this automatically for verified contracts):

Function: transfer(address, uint256)
  to: 0xabcdef...
  amount: 10000000000 (10,000 USDC with 6 decimals)
Event Logs

Every transaction emits events (in the "Logs" tab):

Transfer(
  from: 0x1234...,
  to: 0x5678...,
  value: 1000000000000000000  (1 ETH in wei)
)

Common DeFi Contract Patterns

ERC-20 Token
FunctionWhat to Check
mint()Who can call? If unrestricted → inflation risk
burn()Deflationary mechanism
pause()Can transfers be frozen?
blacklist()Can addresses be blocked?
setFee()Can transfer tax be changed?
Lending Protocol (Aave-style)
FunctionWhat It Does
supply()Deposit collateral
borrow()Take a loan
repay()Pay back loan
liquidationCall()Liquidate unhealthy position
getReserveData()Read pool stats (APY, utilization)
DEX (Uniswap-style)
FunctionWhat It Does
swap()Execute a token swap
mint() / addLiquidity()Provide liquidity
burn() / removeLiquidity()Remove liquidity
getReserves()Current pool balances (determines price)
Show full SKILL.md (279 more words)Show less
Stablecoin (like USDs)
FunctionWhat to Check
mint()How is new supply created? What collateral is accepted?
redeem()Can you always redeem for underlying?
rebase()How yield is distributed (USDs auto-rebases)
collateralRatio()Is it fully backed?

ABI (Application Binary Interface)

The ABI defines how to interact with a contract programmatically:

json
[
  {
    "name": "balanceOf",
    "type": "function",
    "inputs": [{ "name": "account", "type": "address" }],
    "outputs": [{ "name": "", "type": "uint256" }],
    "stateMutability": "view"
  }
]

Where to get ABIs:

  1. Etherscan → Contract tab → "Contract ABI" section
  2. Protocol documentation
  3. GitHub repositories

Proxy Contracts

Many DeFi protocols use proxies (upgradeable contracts):

User → Proxy Contract → Implementation Contract
       (fixed address)   (logic, can be upgraded)

On Etherscan: Look for "Read as Proxy" / "Write as Proxy" tabs. If you see a proxy, click through to read the implementation contract.

Security Checklist for Contract Review

CheckHowRisk If Failed
✅ Contract verifiedGreen checkmark on explorerCan't see what code does
✅ Check owner functionsSearch for onlyOwner, onlyAdminOwner could rug
✅ Check mint capabilitySearch for mint functionInfinite inflation
✅ Check pause/blacklistSearch for pause, blacklistFunds could be frozen
✅ Check fee functionsSearch for fee, taxFees could be raised to 100%
✅ Audit reportCheck project websiteUnaudited = higher risk
✅ Timelock on upgradesCheck if proxy has a timelockInstant upgrade = rug risk

Agent Tips

  1. Verified contract is non-negotiable — never recommend interacting with unverified contracts
  2. "Read as Proxy" — always check for proxy implementation for the real logic
  3. Owner functions are key — what the owner can do defines the trust assumptions
  4. View functions are free — encourage users to read contract state before transacting
  5. Etherscan does the heavy lifting — auto-decodes transactions, ABI, and events
  6. Sperax contracts are verified — USDs, SPA, and Farms contracts on Arbiscan are fully verified and audited

© nirholas, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in data/skills/development/smart-contract-reading-guide of nirholas/three.ws.

Open the folder on GitHubat commit 238ef60

Compare with similar skills

Smart Contract Reading Guide next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Smart Contract Reading Guide compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Smart Contract Reading Guide this skillnirholas/three.ws226—~2.1kAutomated safety check: PassMIT
DeFi Protocol Templateswshobson/agents40k10 repos~1.9kAutomated safety check: PassMIT
Ethskillsaustintgriffith/ethskills294—~1.4kAutomated safety check: PassNone
Chaingptinternet-court/internet-court-skill6.4k1 repos~4kAutomated safety check: PassMIT
Solidity Vulnerability Scanneralt-research2/SolidityGuard104—~1.6kAutomated safety check: NotesCustom licence
Ethskillsaustintgriffith/ethskills294—~3kAutomated safety check: PassNone

Similar skills

  • Solidity templates for DeFi building blocks: staking with reward distribution, an automated market maker, governance tokens and flash loans.

    40k GitHub starsUsed in 10 repos~1.9k tokens
    Backend & APIsAuto-check passed
  • Ethskills

    austintgriffith/ethskills

    Ethereum development knowledge for AI agents — from idea to deployed dApp.

    294 GitHub stars~1.4k tokensUpdated 1 mo ago
    Backend & APIsAuto-check passed
  • Chaingpt

    internet-court/internet-court-skill

    Build with the ChainGPT Web3 AI developer platform. An agent skill from internet-court/internet-court-skill.

    6.4k GitHub starsUsed in 1 repo~4k tokens
    Backend & APIsAuto-check passed
  • Solidity Vulnerability Scanner

    alt-research2/SolidityGuard

    Comprehensive Solidity contract security scanner detecting 104 vulnerability patterns across reentrancy, access control, arithmetic, DeFi, proxy, and token categories.

    104 GitHub stars~1.6k tokensUpdated 3 mo ago
    Backend & APIsAuto-check: notes
  • Ethskills

    austintgriffith/ethskills

    A skill your agent uses when a request involves Ethereum, the EVM, or blockchain systems.

    294 GitHub stars~3k tokensUpdated 1 mo ago
    Backend & APIsAuto-check passed
  • Blockchain Developer

    Microck/ordinary-claude-skills

    Expert blockchain developer specializing in smart contract development, DApp architecture, and DeFi protocols.

    401 GitHub starsUsed in 1 repo~1.7k tokens
    Backend & APIsAuto-check passed

More from nirholas/three.ws

All 165 skills in this repo
  • Add Shader Cursor Trail

    nirholas/three.ws

    Add the Shaders WebGPU mouse effect used for the Tidal Commons hero: a white twinkling halftone cursor trail driven by ChromaFlow, masked through a DotGrid, finished with chromatic ripples and film…

    226 GitHub starsUsed in 1 repo~760 tokens
    Auto-check passed
  • Publish Project To GitHub

    nirholas/three.ws

    Package a finished local project into an intentional GitHub repository, create a strong README and visual preview, push it safely, configure a public GitHub Pages URL when the project is compatible…

    226 GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check: notes
  • Audit a website or digital experience against its supplied source references for originality and plagiarism risk.

    226 GitHub starsUsed in 1 repo~1.8k tokens
    Auto-check passed
  • Turn a completed daily UI inspiration capture into exactly five original landing-page builds, one per separate Codex task, using Sites.

    226 GitHub starsUsed in 1 repo~1.9k tokens
    Auto-check passed
  • Write Like Meng On X

    nirholas/three.ws

    Write, rewrite, review, or continuously refine X/Twitter posts in Meng To's current voice using his deduplicated authored-post corpus, personal and product context, shared resources, and Content…

    226 GitHub starsUsed in 1 repo~2k tokens
    Auto-check passed
  • Browser Video Recording

    nirholas/three.ws

    Create polished 60 fps 4:3 4K browser screen-recording style videos from Codex in-app browser captures, with browser-only crop, natural macOS cursor styling, deliberate click choreography…

    226 GitHub starsUsed in 1 repo~1.5k tokens
    Auto-check passed

Works with

Categories

Questions about Smart Contract Reading Guide

What does Smart Contract Reading Guide do?

How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns. ws. How to read and understand smart contracts — navigating Etherscan, reading Solidity code, understanding ABIs, decoding transactions, and spotting common patterns.

When should I use Smart Contract Reading Guide?

Smart Contract Reading Guide fits situations like: helping users verify contracts; understand DeFi protocol mechanics; decode on-chain activity.

How do I install Smart Contract Reading Guide in Claude Code?

Run `npx skills add nirholas/three.ws --skill smart-contract-reading-guide -a claude-code`. Or copy the skill folder (data/skills/development/smart-contract-reading-guide in nirholas/three.ws) into .claude/skills/smart-contract-reading-guide in your project. Claude Code loads it when a task matches its description.

How do I install Smart Contract Reading Guide in Codex?

Run `npx skills add nirholas/three.ws --skill smart-contract-reading-guide -a codex`. Or copy the skill folder (data/skills/development/smart-contract-reading-guide in nirholas/three.ws) into .agents/skills/smart-contract-reading-guide in your project. Codex loads it when a task matches its description.

Can I use Smart Contract Reading Guide in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add nirholas/three.ws --skill smart-contract-reading-guide -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/smart-contract-reading-guide, .gemini/skills/smart-contract-reading-guide, .github/skills/smart-contract-reading-guide and .opencode/skills/smart-contract-reading-guide in your project.

What does Smart Contract Reading Guide need to run?

SKILL.md names no scripts, command-line tools or credentials: Smart Contract Reading Guide is instructions for the agent only.

Does Smart Contract Reading Guide access the network?

SKILL.md names 5 domains. As links in the text: etherscan.io, arbiscan.io, docs.soliditylang.org, openzeppelin.com and docs.chat.sperax.io. This is read from the text; nothing was executed.

Is Smart Contract Reading Guide safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Smart Contract Reading Guide use?

Smart Contract Reading Guide is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Smart Contract Reading Guide use?

About 2.1k tokens (SKILL.md is roughly 8.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Smart Contract Reading Guide?

Skills that share tags, products or a category with Smart Contract Reading Guide: DeFi Protocol Templates (wshobson/agents, 40k stars), Ethskills (austintgriffith/ethskills, 294 stars), Chaingpt (internet-court/internet-court-skill, 6.4k stars) and Solidity Vulnerability Scanner (alt-research2/SolidityGuard, 104 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Smart Contract Reading Guide?

nirholas (a GitHub user) maintains it in nirholas/three.ws, which has 226 GitHub stars. The repository holds 165 skills in this directory. The repository was last updated on October 7, 2026.

Source: nirholas/three.ws on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.