Install the BSV blockchain agent skill
The bsv-dev skill is a playbook an AI agent loads when it works on the BSV blockchain: who holds the keys, how the user’s wallet connects on a computer or a phone, how a payment moves, when a payment channelTwo parties lock funds in one output and exchange signed updates off the network. Only the last update is broadcast is worth it, when a transaction is final, and how an app reaches Mainnet. Use it when an agent builds your BSV blockchain app and you want it to make the same decisions these docs make, without pasting rules into every project. At the end, the skill is installed for your agent, and in Claude Code the plugin has connected both MCP servers and added the commands /bsv-review and /bsv-design.
Before you begin
- For the plugin, Claude Code 2.1.271 or newer. This guide was tested with Claude Code 2.1.303.
- For any other agent, Node.js 22.20 or newer, for the skills CLI (
npx skills). This guide was tested with the skills CLI 1.7.4. - Node.js 22 or newer, for
@bsv/mcp, which the plugin starts throughnpx.
How it works
The skill decides the defaults, and some steps stay yours:
- The skill
Decides by default
- A BRC-100 wallet for users, and who holds the keys, per money path
- A login that offers BSV Desktop and a phone wallet over Wallet Relay
- BSV Broadcaster for every broadcast and status read, final at
SEEN_ON_NETWORKor later with no competing transaction - Testnet, with fees at 100 sat/kB on both networks, never below the BSV Broadcaster /policy
- One transaction per payment, a payment channel only for many updates between two parties, Rúnar for contracts, 1Color for tokens
- You
Keep these steps
- Run the install commands, since the skill never edits your agent configuration
- Get testnet coins from the faucet
- Approve the wallet's prompts, in BSV Desktop or on your phone
- Say yes before any broadcast, after the agent shows the outputs, total, fee and network
- Set
BSV_NETWORK=mainnetyourself
The skill is SKILL.md plus reference files. They cover custody shapes, BRC-100The standard interface between an app and a wallet wallets and the login, BRC-29The BRC-29 payment protocol: the sender pays a key derived for the recipient, and the recipient collects it with internalizeAction payments, payment channels, BSV Broadcaster (formerly Arcade) and zero-confirmationTreating a payment as final once the network has seen it with no competing transaction, before it is in a block, when @bsv/simple fits, testnet to Mainnet, the threat model and common errors. Generated files add the dated facts, the guardrails and the pinned versions.
The skill also has a manifest.json template, an env.example and rule snippets for CLAUDE.md, AGENTS.md and Cursor. Its two scripts read a transaction status from BSV Broadcaster and check the network when an app starts. For contracts, version 0.1.1 gives the rules for Rúnar from its upstream main branch. For tokens, it gives the encoding of 1Color (BRC-162), whose wallet support is not yet in the official wallet-toolbox or BSV Desktop.
For the login, the skill tells the agent to offer two paths in every new app: BSV Desktop on the same computer, through WalletClient, and a phone wallet such as BSV Browser, paired by QR code through Wallet RelayAn encrypted connection between a web app and a phone wallet, paired by QR code (@bsv/wallet-relay). The app waits while a wallet is locked, instead of treating it as missing. On the phone path, the app’s server decrypts every wallet call and result, so the skill tells the agent to say so to users, for example in the app’s privacy notice.
For payment channels, the skill keeps one transaction per payment by default, and proposes a channel only when the same two parties make many updates in one session, a few dozen or more. Its reference covers when a channel pays off, three ways to build one, and how to open, update and close it. The third way, a channel that a Rúnar contract enforces, and any opening that both wallets fund need the skill’s contract and multi-party funding references, which a later version of the skill adds; version 0.1.1 does not have them yet. The two parties hold every signed state themselves, since BSV Broadcaster refuses a transaction that is not final yet.
The skill works on its own, and better with the two MCP servers of Connect your AI tool with MCP. When one is missing, the skill prints the install command for you to run.
Install the plugin in Claude Code
The plugin holds the skill, the two commands and both MCP servers:
Remove the servers you added by hand
Skip this step if you did not add the servers with claude mcp add. If you did, as in Connect your AI tool with MCP, remove them in that project folder, so Claude Code does not start a second copy of bsv-mcp:
claude mcp remove bsv-docs -s local
claude mcp remove bsv-mcp -s localRemoved MCP server bsv-docs from local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]
Removed MCP server bsv-mcp from local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]Add the marketplace and install
Add the BSV marketplace and install the plugin from it:
claude plugin marketplace add bsv-blockchain/bsv-ai-toolkit && claude plugin install bsv-dev@bsvAdding marketplace…✔ Successfully added marketplace: bsv (declared in user settings)
Installing plugin "bsv-dev@bsv"...✔ Successfully installed plugin: bsv-dev@bsv (scope: user)
2 userConfig options not yet set — run /plugin configure bsv-dev@bsv in Claude Code, or pass --config KEY=VALUE.The plugin installs for your user, so it works in every project.
Set the network and the BSV Broadcaster URL
The plugin has two settings: bsv_network, which is testnet or mainnet, and broadcaster_url, which you leave empty for the public BSV Broadcaster endpoint of the network. Set both, for testnet and the public endpoint:
echo '{"bsv_network":"testnet","broadcaster_url":""}' | claude plugin configure bsv-dev@bsv --values-stdinConfiguration saved. Restart Claude Code to apply it.claude plugin configure bsv-dev@bsv then lists bsv_network as set and broadcaster_url, which is empty, as not set. In Claude Code, /plugin configure bsv-dev@bsv sets the same values.
Check what it installed
Show the parts of the plugin:
claude plugin details bsv-dev@bsvBSV Dev (bsv-dev) 0.1.1
Description: Official BSV Association skill, commands and MCP bundle for building BSV apps on BRC-100 wallets, BSV Broadcaster (formerly Arcade) and Rúnar
Source: bsv-dev@bsv
Component inventory
Skills (3) bsv-design, bsv-dev, bsv-review
Agents (0)
Hooks (0)
MCP servers (2) bsv-mcp, bsv-docs (tool schemas resolved at runtime; not counted)
LSP servers (0)
...bsv-design and bsv-review are the two commands. In claude mcp list, the two servers show as plugin:bsv-dev:bsv-mcp and plugin:bsv-dev:bsv-docs.
The plugin bundles bsv-docs and bsv-mcp, so it replaces the two claude mcp add commands of Connect your AI tool with MCP. It never sets BSV_MCP_ALLOW_MAINNET_BROADCAST, so a Mainnet broadcast by the agent still needs you to set it in the shell that starts Claude Code. A broadcaster_url that points at Mainnet also needs bsv_network set to mainnet, or the server treats it as testnet and that gate does not apply.
Install the skill in another agent
Any agent that reads Agent Skills can load bsv-dev. Run the command in your project folder:
Add the skill
Install the skill with the skills CLI:
npx skills add bsv-blockchain/bsv-ai-toolkitThe skills CLI installs the skill into the project, in the folder each agent reads. To pick the agent, add --agent. With --agent claude-code, for example, the output ends like this:
◇ Installed 1 skill ────────────╮
│ │
│ ✓ bsv-dev (copied) │
│ → ./.claude/skills/bsv-dev │
│ │
├────────────────────────────────╯
│
└ Done! Review skills before use; they run with full agent permissions.The skill ships the same rules as snippets for CLAUDE.md, AGENTS.md and Cursor’s bsv.mdc. Give agents the docs in Markdown shows the CLAUDE.md one.
To add the two MCP servers in Cursor, Windsurf or VS Code, see Use another AI tool.
Use the commands
The plugin adds two commands to Claude Code. Neither broadcasts a transaction or asks for a key.
Review a project
/bsv-review [path] reviews a project against the guardrails G-01 to G-38. With no path, it reviews the current project. The agent:
- runs
check_guardrailswith the absolute path, fixes everyerrorand shows you each change, then runs the check again until it reports 0 errors; - lists the warnings with its judgment on each, and fixes the real ones;
- walks the manual checklist, guardrail by guardrail;
- reviews any Rúnar contract,
*.runar.ts, as an attacker would, and walks guardrails G-35 to G-38 for any payment channel; - checks the trust model in the app’s docs: what users trust in the code the app serves, when a payment counts as final, and what the server can and cannot do with their money;
- ends with a summary.
Design an app
/bsv-design [app name] interviews you, then writes a design for the app. The agent asks six questions, one at a time: what moves value, who holds the keys, browser or server, whether the app signs the same kind of thing repeatedly, tokens or contracts, and when it should reach Mainnet.
Then it shows you a draft design and writes it to docs/design/<YYYY-MM-DD>-<name>-design.md in your project. The design covers who holds the keys, the protocols, the manifest.json, each transaction with its fee, whether a money path with many updates between the same two parties is a payment channel, how the app tracks transactions on BSV Broadcaster, the trust model, the move from testnet to Mainnet, and open questions.
Try the skill
With the skill installed, ask the agent for a feature and follow what it does:
Send the request
Run claude in a project folder and type the request:
add tipping to my React app on BSVFollow what the agent does
The skill tells the agent to state first, in one line, who holds the keys for each payment, and then to read the reference files it needs. It tells the agent to build on testnet, with a login for BSV Desktop and a phone wallet, a network check before every payment and a manifest.json, and to run check_guardrails. Last, it tells the agent to end with a paragraph on what users have to trust and your next steps: get testnet coins from the faucet, then try each payment in the app. What the agent writes varies from run to run.
Claude Code asks you before the agent runs a command, so read each one before you allow it.
Next steps
With the skill installed, connect the servers in another tool, let the agent send a first payment, or plan the move to Mainnet: