git:20260313.28d8d83 to git:20260313.03adaab

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`@aibtc/skills` is the core instruction layer for AI agents interacting with Bitcoin and Stacks blockchain services. Each skill is a self-contained directory containing:

- **`SKILL.md`** — YAML frontmatter + documentation that Claude Code reads to understand available subcommands, arguments, and requirements

- **`AGENT.md`** — Autonomous operation rules: decision logic, prerequisites, safety checks, and error-handling patterns for subagent use

- **`<name>.ts`** — Commander CLI script that outputs a single JSON object to stdout

Skills are invoked directly by Claude Code or run manually via Bun. All output is JSON for reliable parsing.

### Repo Layout

```

skills/

wallet/ # Skill directory (SKILL.md + AGENT.md + wallet.ts)

btc/

stx/

sbtc/

tokens/

nft/

bns/

identity/

signing/

stacking/

defi/

bitflow/

pillar/

query/

x402/

yield-hunter/

credentials/

settings/

what-to-do/ # Multi-step workflow guides (9 guides)

aibtc-agents/ # Community agent configuration registry

src/

lib/ # Shared infrastructure modules

services/ # External API + wallet services

wallet-manager.ts # Wallet load/unlock/persist

hiro-api.ts # Hiro Stacks API client

mempool-api.ts # mempool.space + Hiro Ordinals API client

config/ # Network config, contract addresses, Pillar config, other config utilities

utils/

storage.ts # Read/write ~/.aibtc/config.json and local storage

transactions/ # Transaction builders and helpers

scripts/

generate-manifest.ts # Generates skills.json from SKILL.md frontmatter

validate-frontmatter.ts # Validates all SKILL.md frontmatter fields

skills.json # Auto-generated skill manifest (do not edit manually)

package.json

tsconfig.json

```

## Commands

```bash

# Type-check all TypeScript (must pass before committing)

bun run typecheck

# Validate all SKILL.md frontmatter fields

bun run validate

# Regenerate skills.json from SKILL.md files

bun run manifest

# Build shared library to dist/

bun run build

```

### Running Skills

Every skill is a standalone CLI. Invoke any skill directly:

```bash

# Wallet operations

bun run wallet/wallet.ts status

bun run wallet/wallet.ts unlock --password <password>

# Bitcoin L1

bun run btc/btc.ts balance

bun run btc/btc.ts fees

bun run btc/btc.ts transfer --recipient bc1q... --amount 100000 --fee-rate medium

# Stacks L2

bun run stx/stx.ts get-balance

bun run stx/stx.ts deploy-contract --contract-name foo --code-body '(define-public (hello) (ok true))'

# Network prefix for mainnet (default is testnet)

NETWORK=mainnet bun run btc/btc.ts balance

```

All scripts print a single JSON object to stdout. Errors are also JSON:

```json

{ "error": "Wallet is locked. Run: bun run wallet/wallet.ts unlock --password <password>" }

```

## Architecture

### How Skills Work

Claude Code reads `SKILL.md` to discover subcommands and options, then calls the script:

```

Claude Code

↓ reads SKILL.md for subcommands/args

↓ calls: bun run <skill>/<skill>.ts <subcommand> [--flags]

↓ parses JSON stdout

```

Each skill script uses [Commander.js](https://github.com/tj/commander.js) for argument parsing. Every subcommand handler must print exactly one JSON object and exit.

### Shared Infrastructure (`src/lib/`)

| Module | Purpose |

|--------|---------|

| `src/lib/services/wallet-manager.ts` | Load encrypted wallets, unlock with password, persist session to `~/.aibtc/` |

| `src/lib/utils/storage.ts`, `src/lib/config/` | Read and write `~/.aibtc/config.json` (API keys, active wallet, network) |

| `config/networks.ts` | Network URL selection, x402 API base URL, explorer helpers |

| `config/contracts.ts` | Stacks contract addresses for sBTC, identity, and other protocols |

| `src/lib/services/hiro-api.ts` | Hiro Stacks API client with optional API key and custom URL |

| `src/lib/services/mempool-api.ts` | Bitcoin API client: mempool.space (fees/UTXOs/broadcast) + Hiro Ordinals |

### SKILL.md Frontmatter

Every `SKILL.md` begins with YAML frontmatter that drives skill discovery and the manifest:

```yaml

---

name: btc

---

```

| Field | Description |

|-------|-------------|

| `name` | Skill identifier (matches directory name) |

### AGENT.md Content Guidelines

AGENT.md is intentionally concise (one page). Cover:

1. **Prerequisites** — what must be true before invoking the skill

2. **Decision logic** — when to use which subcommand

3. **Safety checks** — what to verify before write operations (balances, UTXO types, fee impact)

4. **Error handling** — how to interpret error JSON and what to do next

5. **Output handling** — which fields to extract and pass to subsequent steps

### CLI Script Conventions

- Use [Commander.js](https://github.com/tj/commander.js) for argument parsing

- Every subcommand handler: `command.action(async (options) => { ... })`

- Print exactly one JSON object: `console.log(JSON.stringify(result, null, 2))`

- On error: `console.log(JSON.stringify({ error: "descriptive message" })); process.exit(1)`

- Never use `process.exit(0)` explicitly — normal exit is sufficient

- Mark sensitive options (passwords, mnemonics) to avoid accidental logging

- Use `src/lib/` shared modules for wallet access, network config, and API calls

## x402 Service URLs

All three are legitimate production x402 services. Agents can choose any based on needed endpoints.

| Service URL | Operator | Capabilities |

|-------------|----------|-------------|

| `https://x402.biwas.xyz` | biwas/secret-mars | DeFi analytics, market data, wallet analysis |

| `https://x402.aibtc.com` | aibtc | Inference, Stacks utilities, hashing, storage |

| `https://stx402.com` | whoabuddy/arc | AI services, cryptography, storage, utilities, agent registry |

The default `API_URL` in `src/lib/config/networks.ts` points to `x402.biwas.xyz`. Override with the `API_URL` environment variable or use the `settings` skill to configure a persistent default.

```bash

# Use a different x402 service for a single command

API_URL=https://x402.aibtc.com bun run x402/x402.ts list-endpoints

# Explore available endpoints on any service

bun run x402/x402.ts list-endpoints

```

## Skill Authoring Guide

### Adding a New Skill

1. Create `<name>/` in the repo root

2. Add `SKILL.md` with YAML frontmatter (see format above)

3. Add `AGENT.md` covering prerequisites, decision logic, safety checks, and error handling

4. Add `<name>/<name>.ts` — Commander CLI where every subcommand prints JSON to stdout

5. Add an entry to the Skills table in `README.md`

6. Run `bun run manifest` to update `skills.json`

7. Run `bun run typecheck` to verify TypeScript

8. Commit: `feat(<name>): add <name> skill`

### Adding a Workflow Guide

Workflow guides in `what-to-do/` combine multiple skills into complete end-to-end operations.

1. Add `what-to-do/<slug>.md` with YAML frontmatter:

```yaml

---

title: Workflow Title

description: One-line description.

skills: [wallet, btc, stx]

estimated-steps: 5

order: 10

---

```

2. Structure: goal description, prerequisites checklist, ordered steps with `bun run` commands and expected output, verification checklist, Related Skills table, See Also links

3. Update `what-to-do/INDEX.md` and the Workflow Discovery table in `README.md`

4. Commit: `docs(what-to-do): add <workflow-name> workflow`

**Important:** Workflow steps must use `bun run` CLI invocations, not MCP tool names. Use `curl`/`wget` for aibtc.com API calls (the platform detects CLI user-agents and returns plaintext).

## Contribution Guidance

See [CONTRIBUTING.md](./CONTRIBUTING.md) for full details. Key requirements:

- `bun run typecheck` must pass before submitting a PR

- All commits follow [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): description`

- Never commit private keys, seed phrases, passwords, or raw API key values

- Shared infrastructure changes go in `src/lib/` — do not re-implement wallet, config, or network logic in individual skills

### Common Commit Scopes

`wallet`, `btc`, `stx`, `sbtc`, `tokens`, `nft`, `bns`, `identity`, `signing`, `stacking`, `defi`, `bitflow`, `pillar`, `query`, `x402`, `yield-hunter`, `credentials`, `settings`, `what-to-do`, `aibtc-agents`, `src`

### Release Process

This repo uses [Release Please](https://github.com/googleapis/release-please) for automated releases. Merge conventional commits to `main` — Release Please auto-creates a release PR with updated `CHANGELOG.md` and version bump. Merge the release PR to publish.

## Key Files Reference

| File / Path | Purpose |

|-------------|---------|

| `skills.json` | Auto-generated manifest — run `bun run manifest` to update |

| `package.json` | Version source of truth — manifest reads version from here |

| `tsconfig.json` | TypeScript strict mode configuration |

| `scripts/generate-manifest.ts` | Globs all `*/SKILL.md`, parses frontmatter, writes `skills.json` |

| `scripts/validate-frontmatter.ts` | Validates required frontmatter fields across all skills |

| `src/lib/config/networks.ts` | Network URL selection, x402 default API URL |

| `src/lib/config/contracts.ts` | Stacks contract addresses (sBTC, identity registry, etc.) |

| `src/lib/services/wallet-manager.ts` | Shared wallet load/unlock/persist logic |

| `src/lib/services/hiro-api.ts` | Hiro Stacks API client |

| `src/lib/services/mempool-api.ts` | mempool.space + Hiro Ordinals API client |

| `what-to-do/INDEX.md` | Index of all workflow guides |

| `aibtc-agents/README.md` | Community agent registry contribution guide |

| `aibtc-agents/template/setup.md` | Agent config template to copy |

| `aibtc-agents/arc0btc/README.md` | Reference agent configuration |