8004skill

An AI agent skill for interacting with the ERC-8004 on-chain agent economy. Register agents, discover peers, manage reputation, and enable agent-to-agent interactions across EVM chains.

How It Works

8004skill is a conversational skill for AI coding agents, compatible with Claude Code, OpenClaw, and other Agent Skills-compatible tools. Once installed, the agent reads the skill definition and guides you through every operation as an interactive wizard. You never construct commands, remember flags, or read script output directly -- you just talk to the agent.

``
You ──ask in natural language──> Agent ──reads──> SKILL.md
│
├── runs the right script for you
├── gathers inputs step by step
├── asks for confirmation before writes
└── presents results back in plain English
`

Example prompts you can use:

- "Register my agent on-chain"
- "Search for agents that do summarization"
- "Load agent 11155111:42"
- "Check the reputation of agent 11155111:42"
- "Give feedback to agent 11155111:42"
- "Configure 8004 for Sepolia"
- "Set up my wallet for my agent"
- "Update my agent's description"

Any of these (or similar phrasing) will start the corresponding wizard flow. If the agent is unsure what you need, it will show you the full operations menu.

Usage Guide

See the Usage Guide for agent-specific setup and workflows (Claude Code, OpenClaw, and other SKILL.md-compatible agents).

Prerequisites

- Node.js >= 22.0.0
- Platform: macOS or Linux (Windows is not supported)
- A SKILL.md-compatible AI agent such as Claude Code, OpenClaw, or similar

Quick Install

`bash
npx 8004skill install
`

Downloads the skill, installs dependencies, and links it to your agent. Supports Claude Code and OpenClaw.

$3

From source (git clone):

`bash
git clone https://github.com/matteoscurati/8004skill.git
cd 8004skill
./install.sh
`

Via skill manager:

`bash
npx skills add matteoscurati/8004skill
npx openskills install matteoscurati/8004skill
`

The install wizard checks prerequisites, installs npm dependencies, and symlinks the skill into the agent(s) of your choice (~/.claude/skills/ and/or ~/.openclaw/skills/). After that, every SKILL.md-compatible agent on your machine will discover the skill automatically.

You can also install manually — see Manual installation below.

Quick Start

Here is the fastest path from install to your first operation:

$3

Follow the Quick Install steps above.

$3

Open your agent in any directory and say:

> "Configure 8004 for Sepolia"

The agent will walk you through selecting a chain, RPC endpoint, and (optionally) an IPFS provider. Configuration is saved to ~/.8004skill/config.json.

$3

Once configured, try a search:

> "Search for agents that do summarization"

The agent will run the search and present results as a readable table. From there you can ask to load details, check reputation, or give feedback -- all conversationally.

$3

To register an agent, submit feedback, or manage wallets, you need to pair a wallet via WalletConnect. Ask your agent:

> "Configure 8004 for Sepolia"

During configuration, the agent will show a QR code in the terminal. Scan it with your wallet app (MetaMask, Rainbow, etc.) to establish a session. Then:

> "Register my agent on-chain"

The agent will gather the required inputs (name, description, endpoints) step by step, show a confirmation summary, and submit the transaction only after you approve in both the chat and your wallet app.

Configuration

The skill stores configuration at ~/.8004skill/config.json, created automatically when you run the Configure wizard:

`json
{
"activeChain": 11155111,
"rpcUrl": "https://rpc.sepolia.org",
"ipfs": "pinata",
"wcProjectId": "optional-walletconnect-project-id",
"registrations": {}
}
`

| Field | Description |
|-------|-------------|
| activeChain | Chain ID for the active network |
| rpcUrl | RPC endpoint for the active chain |
| ipfs | IPFS pinning provider (pinata, filecoinPin, node, or null) |
| wcProjectId | WalletConnect project ID (optional; a default is provided) |
| registrations | Record of agents you have registered, keyed by chain ID |

Environment Variables

| Variable | Required For | Description |
|----------|-------------|-------------|
| WC_PROJECT_ID | All WC operations (optional) | WalletConnect project ID from cloud.walletconnect.com. A default is provided if not set. |
| PINATA_JWT | ipfs: "pinata" | JWT token for Pinata pinning |
| FILECOIN_PRIVATE_KEY | ipfs: "filecoinPin" | Private key for Filecoin pinning |
| IPFS_NODE_URL | ipfs: "node" | URL of the IPFS node API |

> Note: The three IPFS variables are mutually exclusive — you only need the one that matches the provider you selected during configuration. IPFS is optional and only required for write operations that store metadata (agent registration, feedback with text). If a credential is not set when needed, the agent will prompt for it inline (not persisted).

Variables can be exported in the shell or defined in ~/.8004skill/.env (shell values take precedence). Copy the included .env.example to get started:

`bash
cp .env.example ~/.8004skill/.env
chmod 600 ~/.8004skill/.env
`

Read operations (search, load agent, check reputation) do not require a wallet connection. All 3 supported chains (Mainnet, Sepolia, Polygon) work out of the box with built-in registry addresses and subgraph URLs.

Supported Chains

The SDK supports 3 chains:

| Chain | Chain ID | SDK Support |
|-------|----------|-------------|
| Ethereum Mainnet | 1 | Full (registry + subgraph) |
| Ethereum Sepolia | 11155111 | Full (registry + subgraph) |
| Polygon Mainnet | 137 | Full (registry + subgraph) |

Additional chains are deployed on-chain but not yet supported by the SDK. See reference/chains.md for the full list.

Manual Installation

`bash
git clone https://github.com/matteoscurati/8004skill.git
cd 8004skill
npm install

Claude Code

mkdir -p ~/.claude/skills
ln -s "$(pwd)" ~/.claude/skills/8004skill

OpenClaw

mkdir -p ~/.openclaw/skills
ln -s "$(pwd)" ~/.openclaw/skills/8004skill
`

CLI Management

The 8004skill CLI provides commands for managing the skill installation:

`bash
npx 8004skill install # Install or reinstall the skill
npx 8004skill uninstall # Remove symlinks, installed files, and optionally user data
npx 8004skill update # Pull latest changes (git clone) or re-copy files (npx) and refresh deps
npx 8004skill doctor # Check installation, symlinks, scripts, config, and WalletConnect status
`

From a git clone, you can also use node bin/cli.mjs .

Security

- Private keys never touch the agent. All signing is done via WalletConnect v2 — transactions are signed in the user's wallet app (MetaMask, Rainbow, etc.).
- The WalletConnect session file (~/.8004skill/wc-storage.json) contains only relay metadata, no key material.
- The skill runs a preflight check before every write operation to confirm the connected wallet address.
- All on-chain writes require explicit user confirmation before submission.
- Config files are created with chmod 600` (owner-only read/write).

Contributing

See CONTRIBUTING.md for development setup, project structure, and contribution guidelines.

License

This project is licensed under the GPL-3.0 License.