# Install the BSV blockchain agent skill

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

Install the bsv-dev skill or the Claude Code plugin, so your agent builds BSV blockchain apps the way these docs do, on testnet.

import SkillRoles from '/snippets/SkillRoles.jsx';

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 channel (Two 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](https://code.claude.com/docs/en/overview) 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 through `npx`.

## How it works

The skill decides the defaults, and some steps stay yours:

<SkillRoles />

- The skill, decides by default: a BRC-100 wallet for users, with the wallet's identity key as the user's id; a login that offers BSV Desktop through `WalletClient` and a phone wallet such as BSV Browser, paired by QR code through Wallet Relay, and waits for a locked wallet; who holds the keys, per money path, with the user's wallet preferred when both work; BSV Broadcaster (formerly Arcade) for every broadcast and status read, final at `SEEN_ON_NETWORK` or later with no competing transaction; `WalletClient('auto', originator)` from `@bsv/sdk` 3.x; testnet unless `BSV_NETWORK=mainnet`; fees sized from the serialized transaction at 100 sat/kB on both networks, never below the BSV Broadcaster policy; one transaction per payment, and a payment channel only for many updates between the same two parties; Rúnar for contracts and 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 and approve the wallet's prompts, in BSV Desktop or on your phone; say yes before any broadcast, after the agent shows the outputs, the total, the fee and the network; set `BSV_NETWORK=mainnet` yourself, when the app is ready.

The skill is `SKILL.md` plus reference files. They cover custody shapes, BRC-100 (The standard interface between an app and a wallet) wallets and the login, BRC-29 (The 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-confirmation (Treating 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](https://bsvblockchain.com/docs/wallets/bsv-browser/), paired by QR code through Wallet Relay (An 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](https://bsvblockchain.com/docs/build-with-ai/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:

**1. 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](https://bsvblockchain.com/docs/build-with-ai/mcp/), remove them in that project folder, so Claude Code does not start a second copy of `bsv-mcp`:

```bash
claude mcp remove bsv-docs -s local
claude mcp remove bsv-mcp -s local
```

```text
Removed 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]
```

**2. Add the marketplace and install**

Add the BSV marketplace and install the plugin from it:

```bash
claude plugin marketplace add bsv-blockchain/bsv-ai-toolkit && claude plugin install bsv-dev@bsv
```

```text
Adding 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.

**3. 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:

```bash
echo '{"bsv_network":"testnet","broadcaster_url":""}' | claude plugin configure bsv-dev@bsv --values-stdin
```

```text
Configuration 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.

**4. Check what it installed**

Show the parts of the plugin:

```bash
claude plugin details bsv-dev@bsv
```

```text
BSV 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](https://bsvblockchain.com/docs/build-with-ai/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:

**1. Add the skill**

Install the skill with the skills CLI:

```bash
npx skills add bsv-blockchain/bsv-ai-toolkit
```

The 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:

```text
◇  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](https://bsvblockchain.com/docs/build-with-ai/llm-resources/) shows the `CLAUDE.md` one.

To add the two MCP servers in Cursor, Windsurf or VS Code, see [Use another AI tool](https://bsvblockchain.com/docs/build-with-ai/mcp/#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_guardrails` with the absolute path, fixes every `error` and 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:

**1. Send the request**

Run `claude` in a project folder and type the request:

```text
add tipping to my React app on BSV
```

**2. Follow 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:

- [Connect your AI tool with MCP](https://bsvblockchain.com/docs/build-with-ai/mcp/)
- [Send a payment with an AI agent](https://bsvblockchain.com/docs/build-with-ai/prompts/)
- [Move your app to mainnet](https://bsvblockchain.com/docs/guides/go-to-mainnet/)