# Use it with AI agents

> Let Claude Code, Cursor or any coding agent scaffold and extend BSV apps. One JSON file in, an AGENTS.md out, and docs every agent can read.

> Agents: search these docs with the `search_docs` tool on the MCP server at https://createbsvapp.vercel.app/mcp, or read everything at https://createbsvapp.vercel.app/llms-full.txt.

create-bsv-app was built to be driven by agents as well as people. Three things make that work: a **deterministic input** (`--file`), a **generated guide** in every project (`AGENTS.md`), and **docs agents can read** (Markdown at stable URLs).

## Give your agent the skill

The fastest setup is a skill: a short instruction file that teaches an agent the commands, flags and gotchas. We publish one.

::: code-group
```bash [Claude Code]
mkdir -p .claude/skills/create-bsv-app
curl -fsSL https://createbsvapp.vercel.app/.well-known/agent-skills/create-bsv-app/SKILL.md \
  -o .claude/skills/create-bsv-app/SKILL.md
```
```bash [any agent]
curl -fsSL https://createbsvapp.vercel.app/.well-known/agent-skills/create-bsv-app/SKILL.md
# paste it into your agent's rules or system prompt
```
:::

The CLI package also ships a smaller skill (`scaffolding-bsv-apps`) inside `node_modules/create-bsv-app/.claude/skills/`. Ours adds the troubleshooting knowledge from these docs.

## Connect the docs over MCP

These docs are also a read-only [MCP](https://modelcontextprotocol.io) server, so your agent can search and read them mid-task instead of guessing:

::: code-group
```bash [Claude Code]
claude mcp add --transport http create-bsv-app-docs https://createbsvapp.vercel.app/mcp
```
```json [any MCP client]
{
  "mcpServers": {
    "create-bsv-app-docs": { "type": "http", "url": "https://createbsvapp.vercel.app/mcp" }
  }
}
```
:::

| Tool | What it does |
| --- | --- |
| `search_docs` | full-text search over every section; returns page slugs and anchors |
| `get_page` | one page as Markdown, by slug (`tutorial`, `cli`, `troubleshooting`…) |
| `list_pages` | every page with its one-line summary |

No auth, no state, and it only reads the published docs.

## Prompts that work

```text [scaffold]
Scaffold a full-stack BSV app called "tipjar" with wallet login and signed requests
using create-bsv-app. Run it non-interactively, then read AGENTS.md and summarise
the routes and hooks I can use.
```

```text [add a feature]
Using the signed-requests capability, add POST /api/tips that records
{ identityKey, amount, note } and a React form that calls it with signedFetch.
Follow the patterns in AGENTS.md and add a node:test test like
https://createbsvapp.vercel.app/docs/testing.md
```

```text [existing app]
Add wallet-connect and wallet-login to this repo with create-bsv-app in add mode,
then apply the "Wiring (manual)" section of the generated AGENTS.md.
```

## Rules for agents

::: danger Never run it interactively
`npx create-bsv-app` with no flags waits on prompts that an agent can't answer. Always pass `--yes` or `--file`.
:::

- **New project:** `npx create-bsv-app@latest <dir> --starter full-stack --capabilities wallet-login,signed-requests --yes`
- **Existing project:** `npx create-bsv-app@latest add --capabilities wallet-connect,<more> --yes`. List `wallet-connect` explicitly the first time, because add mode doesn't expand dependencies.
- **Non-npm package managers:** add `--package-manager pnpm|yarn|bun`. It isn't auto-detected.
- **Errors** go to stderr, the exit code is `1`, and config problems start with `Invalid config:`. The message says what to change.
- **After scaffolding**, read `AGENTS.md` before writing code. It has the exact function signatures, file paths and wiring for every installed capability.

## The deterministic door: `--file`

Everything the prompts ask, as JSON. Same pipeline, same output, no prompts:

```json [config.json]
{
  "mode": "new",
  "name": "tipjar",
  "starter": "full-stack",
  "capabilities": ["wallet-login", "signed-requests"],
  "packageManager": "npm",
  "network": "test",
  "install": true
}
```

```bash
npx create-bsv-app@latest --dir tipjar --file config.json
```

Every field is in the [ProjectConfig reference](https://createbsvapp.vercel.app/docs/config). Check the file into your repo and the scaffold is reproducible.

## What's in AGENTS.md

Every generated project gets one at its root, rebuilt on every run:

- **Install:** the exact dependency ranges added to each package.
- **Wiring:** "wired automatically", or in add mode / `--no-glue`, the exact snippets to paste into `main.tsx`, `App.tsx` and the server entry.
- **Per capability:** *How it works*, *How it's used* (files and function signatures) and *Future integrations* (sessions, persistence, Redis nonces and more).

## Docs built for context windows

| URL | What you get |
| --- | --- |
| [`/llms.txt`](https://createbsvapp.vercel.app/llms.txt) | an index of every page, with one-line summaries |
| [`/llms-full.txt`](https://createbsvapp.vercel.app/llms-full.txt) | the entire docs site as one Markdown file |
| `/docs/<page>.md` | any page as Markdown, e.g. [`/docs/cli.md`](https://createbsvapp.vercel.app/docs/cli.md) |
| any page + `Accept: text/markdown` | the same Markdown via content negotiation |
| [`/.well-known/agent-skills/index.json`](https://createbsvapp.vercel.app/.well-known/agent-skills/index.json) | discoverable skills, with SHA-256 digests |
| `/mcp` | the MCP server above (card at [`/.well-known/mcp/server-card.json`](https://createbsvapp.vercel.app/.well-known/mcp/server-card.json)) |

```bash
curl -H "Accept: text/markdown" https://createbsvapp.vercel.app/docs/capabilities
```

Every page also has **Copy page** and **Ask Claude / ChatGPT** buttons, top right.