contract-learner

Category: Tools & Productivity | Uploader: keypo-us | Downloads: 0 | Version: v1.0（Latest）
Use when a user provides a smart contract address and wants to generate a reusable SKILL.md file for interacting with that contract through keypo-wallet. Analyzes verified contracts by fetching their ABI, categorizes functions, and outputs a complete agent skill file with verified addresses, function signatures, calldata encoding instructions, and keypo-wallet execution commands. Also use when a user says "make a skill for this contract", "generate a skill", or "I want to interact with this contract using keypo-wallet". Requires Foundry (cast) to be installed.
Changelog: Source: GitHub https://github.com/keypo-us/keypo-wallet
Directory Structure

Current level: skills/contract-learner/
📄 SKILL.md 11.2 KB
SKILL.md

---
name: contract-learner
description: Use when a user provides a smart contract address and wants to generate a reusable SKILL.md file for interacting with that contract through keypo-wallet. Analyzes verified contracts by fetching their ABI, categorizes functions, and outputs a complete agent skill file with verified addresses, function signatures, calldata encoding instructions, and keypo-wallet execution commands. Also use when a user says "make a skill for this contract", "generate a skill", or "I want to interact with this contract using keypo-wallet". Requires Foundry (cast) to be installed.
license: MIT
metadata:
  author: keypo-us
  version: "0.1.0"
  compatibility: Requires Foundry (cast). Works with any EVM chain that has an Etherscan-compatible block explorer.
---

# Contract Learner — SKILL.md Generator for keypo-wallet

Given a deployed smart contract address, this skill generates a complete, portable SKILL.md file that teaches any agent how to interact with that contract using keypo-wallet as the execution backend.

**This skill does not execute transactions itself.** It produces SKILL.md files that do.

---

## Prerequisites — Check These First

Before doing anything else, resolve these two dependencies. Do not proceed until both are confirmed.

### Locate cast

Foundry's `cast` is required. Check for it in this order:

```bash
# Check PATH first
which cast 2>/dev/null || \
# Foundry's default install location
ls ~/.foundry/bin/cast 2>/dev/null || \
echo "CAST_NOT_FOUND"
```

If found at `~/.foundry/bin/cast`, use the full path for all commands in this skill (e.g., `~/.foundry/bin/cast call ...`). Set a variable for convenience:

```bash
CAST=$(which cast 2>/dev/null || echo ~/.foundry/bin/cast)
```

If not found at either location, tell the user to install Foundry: `curl -L https://foundry.paradigm.xyz | bash && foundryup`

### Verify Etherscan API key

An Etherscan API key is **required** to fetch contract ABIs. Check for it immediately:

```bash
echo $ETHERSCAN_API_KEY
```

If the variable is set, use it silently — do not print it or include it in any output.

If empty, **tell the user to set it in their shell environment.** Do not ask them to paste the key into the chat — keys entered in conversation are stored in chat history and may be synced or logged. Instead, instruct them:

```
Please set your Etherscan API key as an environment variable before proceeding.
Add this to your ~/.zshrc (or ~/.bashrc) and restart your terminal:

  export ETHERSCAN_API_KEY="your-key-here"

Free keys are available at https://etherscan.io/myapikey and work across all chains.
Then re-run this command.
```

Do not proceed without the key. Do not attempt to fetch ABIs without a key — it will fail.

---

## Input

The user provides:
- **Contract address** — `0x...` (42 characters, required)
- **Chain** — chain name or ID (required)
- **Skill name** — lowercase hyphenated name for the output skill (optional, will be inferred from contract name)

---

## Process

### 1. Resolve the chain

Map the user's chain input to a chain ID and RPC URL:

| Chain | Chain ID | RPC URL | Explorer API Base |
|-------|----------|---------|-------------------|
| Ethereum | 1 | `https://eth.llamarpc.com` | `https://api.etherscan.io/v2/api?chainid=1` |
| Base | 8453 | `https://mainnet.base.org` | `https://api.etherscan.io/v2/api?chainid=8453` |
| Base Sepolia | 84532 | `https://sepolia.base.org` | `https://api.etherscan.io/v2/api?chainid=84532` |
| Arbitrum | 42161 | `https://arb1.arbitrum.io/rpc` | `https://api.etherscan.io/v2/api?chainid=42161` |
| Optimism | 10 | `https://mainnet.optimism.io` | `https://api.etherscan.io/v2/api?chainid=10` |
| Polygon | 137 | `https://polygon-rpc.com` | `https://api.etherscan.io/v2/api?chainid=137` |
| Sepolia | 11155111 | `https://rpc.sepolia.org` | `https://api.etherscan.io/v2/api?chainid=11155111` |

### 2. Fetch the ABI

**Only use the Etherscan API to fetch ABIs. Never try to scrape or fetch block explorer web pages (basescan.org, etherscan.io, etc.) — they return 403 errors and HTML, not ABI data.**

Use `cast interface` with the API key:

```bash
$CAST interface <address> --chain <chain-id> --etherscan-api-key $ETHERSCAN_API_KEY
```

If `cast interface` fails, fall back to the Etherscan V2 REST API:

```bash
curl -s "https://api.etherscan.io/v2/api?chainid=<chain-id>&module=contract&action=getabi&address=<address>&apikey=$ETHERSCAN_API_KEY"
```

The response JSON has `result` containing the ABI as a JSON string. Parse it to get the function list.

**If the contract is not verified:** Stop and tell the user. You cannot generate a skill for an unverified contract. They can provide the ABI manually as a JSON file.

**If the contract is a proxy:** Detect proxy patterns (implementation(), upgradeTo()). Follow the proxy to the implementation:

```bash
$CAST call <proxy-address> "implementation()(address)" --rpc-url <rpc-url>
$CAST interface <implementation-address> --chain <chain-id> --etherscan-api-key $ETHERSCAN_API_KEY
```

Use the proxy address in the generated skill (that's what users send transactions to) but note it's a proxy in the skill's description.

### 3. Gather contract metadata

Before generating the skill, collect these details using read calls:

```bash
# For tokens — try these, they may revert on non-token contracts
$CAST call <address> "name()(string)" --rpc-url <rpc-url>
$CAST call <address> "symbol()(string)" --rpc-url <rpc-url>
$CAST call <address> "decimals()(uint8)" --rpc-url <rpc-url>

# Verify the contract has code deployed
$CAST code <address> --rpc-url <rpc-url>
```

If name/symbol return values, this is likely a token contract. Include the decimals value in the generated skill — this is critical for correct amount encoding.

### 4. Categorize functions

From the ABI, sort functions into three groups:

- **Write functions** — not `view` or `pure`, these require keypo-wallet to execute
- **Read functions** — `view` or `pure`, these use `cast call` directly
- **Payable functions** — subset of write functions that accept ETH, require `--value` flag

### 5. Generate the SKILL.md

Produce a SKILL.md file following the output template below. Replace all `<placeholders>` with actual values from the contract analysis. Remove any sections that don't apply (e.g., remove the Payable section if there are no payable functions).

Write the file to `./<skill-name>/SKILL.md`.

---

## Output Template

The generated SKILL.md must follow this structure exactly. This ensures consistency across all generated skills and compatibility with keypo-wallet.

````markdown
---
name: <skill-name>
description: Interact with <contract-name> (<symbol-if-token>) at <address> on <chain-name>. <one-sentence description of what the contract does based on its functions>. Use with keypo-wallet for transaction execution — use `cast calldata` to encode function calls and pipe to `keypo-wallet send` or `keypo-wallet batch`.
license: MIT
metadata:
  author: auto-generated by contract-learner
  version: "1.0.0"
  source-contract: <address>
  chain: <chain-name>
  chain-id: <chain-id>
  generated: <YYYY-MM-DD>
---

# <Contract Name> (<chain-name>)

| Field | Value |
|-------|-------|
| Address | `<address>` |
| Chain | <chain-name> (Chain ID: <chain-id>) |
| Type | <token / protocol / proxy — inferred from functions> |
| Decimals | <decimals — only if token> |
| Symbol | <symbol — only if token> |
| RPC | `<rpc-url>` |

**Auto-generated from verified ABI.** Do not modify the address or function signatures.

---

## Read Functions

Use `cast call` — no wallet needed, no gas cost.

### <function-name>

```bash
cast call <address> "<signature>(<return-types>)" <arg-placeholders> --rpc-url <rpc-url>
```

<Repeat for each read function>

---

## Write Functions

Encode calldata with `cast calldata`, then execute via keypo-wallet.

### <function-name>

```bash
CALLDATA=$(cast calldata "<signature>" <arg-placeholders>)
keypo-wallet send --key <key-name> --to <address> --data $CALLDATA
```

<If payable, add: `# This function is payable — add --value <wei> to send ETH`>
<Add verification step: show the read function to confirm the result>

<Repeat for each write function>

---

## Common Patterns

<Include this section only if the contract has functions that naturally compose>

### Approve + <Action>

```bash
APPROVE_DATA=$(cast calldata "approve(address,uint256)" <this-contract-address> <amount>)
ACTION_DATA=$(cast calldata "<action-signature>" <args>)

echo "[
  {\"to\": \"<token-address>\", \"value\": \"0\", \"data\": \"$APPROVE_DATA\"},
  {\"to\": \"<address>\", \"value\": \"0\", \"data\": \"$ACTION_DATA\"}
]" | keypo-wallet batch --key <key-name> --calls -
```

---

## Amount Encoding

<Include this section only for token contracts>

This token uses **<decimals> decimals**. Always convert human-readable amounts:

| Human Amount | Raw Amount |
|-------------|------------|
| 1.0 | <10^decimals> |
| 0.01 | <10^(decimals-2)> |
| 100 | <100*10^decimals> |

To transfer 1.0 <symbol>:

```bash
CALLDATA=$(cast calldata "transfer(address,uint256)" <recipient> <10^decimals>)
keypo-wallet send --key <key-name> --to <address> --data $CALLDATA
```
````

---

## Rules for Generation

1. **Include only functions from the actual ABI.** Never add functions that aren't in the contract.

2. **Always hardcode the verified contract address.** The generated skill must contain the exact address — never let the consuming agent guess or substitute addresses.

3. **Include the chain ID and RPC URL.** The generated skill must be chain-specific. If the same contract exists on multiple chains, generate separate skills or include a chain table.

4. **For token contracts, always include the Amount Encoding section.** This prevents the most common agent error — sending wrong amounts.

5. **Use `cast calldata` for encoding, not manual hex.** The consuming agent runs `cast calldata` at execution time. This keeps generated skills readable and correct.

6. **For proxy contracts, note it in the description** but use the proxy address (not the implementation) for all execution commands.

7. **Group related functions.** If the contract has approve + transferFrom, show the batched pattern. If it has deposit + withdraw, group them.

8. **Omit admin-only functions** like `onlyOwner`, `renounceOwnership`, `upgradeTo` unless the user specifically asks for them.

9. **Include verification steps.** After every write function, show the corresponding read function to check the result (e.g., after `transfer`, show `balanceOf`).

10. **Test the generated skill before saving.** Run at least one read function to verify the address and RPC are working:
    ```bash
    $CAST call <address> "<simplest-read-function>" --rpc-url <rpc-url>
    ```
    If this fails, the generated skill is broken — fix before writing to disk.

---

## After Generation

1. Write the file to `./<skill-name>/SKILL.md`
2. Print a summary: skill name, contract address, chain, number of read/write/payable functions
3. Run one read function to verify the skill works
4. Show the user how to install it:
   ```
   # Use in current project (Claude Code)
   cp -r ./<skill-name> .claude/skills/

   # Or add to keypo-wallet's skills directory
   cp -r ./<skill-name> skills/

   # Or publish to GitHub for npx skills add
   # Push the <skill-name>/ folder to a repo, then:
   # npx skills add <owner>/<repo> --skill <skill-name>
   ```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
contract-learner

Directory Structure

SKILL.md

Report

Notice
