Skills and ready prompts that let Claude Code, Cursor, Codex or Copilot add tracing to your on-chain code, explain a failed transaction and use the right OpenTelemetry names. Install them with one command, or copy a prompt.
$ npx skills add https://hashspan.dev
Run it in your project root. The installer asks which agents to set up and puts each skill in that agent’s skills folder. Commit the folder, so everyone on the project gets the same steps.
What can I ask my coding agent to do?
Copy a prompt into your agent. Each one names the skill or page it should follow, so it works with or without the skills installed.
Add tracing to a viem agent
Every transaction your agent or service sends through viem becomes send and confirm spans in its own trace.
Use the hashspan skill to add hashspan to this project, so every transaction it sends through viem shows up as OpenTelemetry spans. Run it only against a local chain with Anvil’s test accounts, ask me before anything signs, and don’t read .env files or keys. Then run the typecheck and tests.
You should see: Each transaction shows send {chainId} and confirm {chainId} spans under the span that was active when it was sent.
Each paid request your agent makes with an x402 client gets a payment span and, with a reader, its settlement a confirm span.
Use the hashspan skill to trace the x402 payments this project makes: wrap the x402 client with @hashspan/x402 right after it is created. Run it only against a local chain or a testnet I name, ask me before anything signs, and don’t read .env files or keys. Then run the typecheck and tests.
You should see: Each x402 payment shows a payment {chainId} span and, with a reader, a confirm {chainId} span.
Paste the error. The agent finds where the transaction stopped, the likely cause in your code and the fix.
Use the explain-evm-error skill (or read https://hashspan.dev/errors.md) to explain this transaction error: where it stopped, the likely cause and the fix. Don’t send or sign anything.
<paste the full error here>
Search your traces for transactions that reverted, by agent, and read the decoded revert reason.
Our transactions are traced with hashspan. Following https://hashspan.dev/docs/recipes/find-reverted-transactions.md, show me how to find the traces where a transaction reverted in our tracing backend, filtered by agent, and where the revert reason is.
Before code sets or queries gen_ai.*, rpc.*, http.* or blockchain.* attributes, check the exact name, type and stability.
Use the otel-attribute-names skill (or https://hashspan.dev/learn/otel-attributes.md) to check every OpenTelemetry attribute name this code sets or queries. Fix renamed ones, and don’t invent names.
Instruments a TypeScript project with hashspan, so that every on-chain transaction or agent payment it sends becomes OpenTelemetry send, payment and confirm spans inside the active trace, exported to Jaeger or any OTLP backend. Use when a project, an AI agent or any other service, sends EVM transactions or x402 payments through viem, the Coinbase CDP SDK, x402 or MPP and uses or wants OpenTelemetry tracing of them.
Explains an EVM transaction error and how to fix it, from the error pages on hashspan.dev, which list the exact messages that viem, wallets and JSON-RPC nodes print. Use when a transaction was rejected, reverted, ran out of gas, got stuck pending or was dropped and replaced, or when the user pastes an Ethereum error message such as "nonce too low" or "execution reverted".
Looks up exact OpenTelemetry attribute names before code sets, renames or queries them, with type, stability and renamed names, from the attribute lookup on hashspan.dev. Covers gen_ai.*, mcp.*, rpc.*, jsonrpc.*, http.*, error.type, server.* and client.*, plus hashspan's blockchain.*, x402.* and mpp.*. Use when writing span attributes or instrumentation, building dashboards or trace queries, or reviewing attribute names, for example for AI agents and LLM calls.
Setting hashspan up by hand, or want a rules snippet for your agent? See Build with AI and the Quickstart.
FAQ
What is an agent skill?
A folder with a SKILL.md file: instructions a coding agent loads when a task matches the skill’s description. Claude Code, Cursor, Codex, GitHub Copilot and many other agents read the same format, so one skill works in all of them.
How do I install only one skill?
Add --skill and its name, such as npx skills add https://hashspan.dev --skill explain-evm-error. The hashspan skill also installs from its repository: npx skills add selimaytac/hashspan.
Do the skills send transactions?
No. explain-evm-error and otel-attribute-names only read and explain. The hashspan skill edits your code and runs your checks; it tells the agent to run only against a local chain or a testnet you name, and to ask before anything signs.
My agent has no skills support. Can it still use these?
Yes. Paste a prompt from this page: each one links the page or skill file the agent should read, so any agent that can fetch a URL can follow it. Agents that use the Context7 MCP server can also read the hashspan docs there.
Where do the skills come from?
The hashspan skill is the one in the hashspan repository, served here at the version on npm. The other two are written from the error pages and the attribute lookup on this site. All three are plain Markdown you can read before installing.