diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..55dd7ca --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,35 @@ +{ + "name": "bitbadges", + "owner": { + "name": "BitBadges", + "email": "support@bitbadges.io", + "url": "https://bitbadges.io" + }, + "plugins": [ + { + "name": "bitbadges", + "source": "./", + "description": "BitBadges builder skills for Claude Code. Auto-wires the bitbadges-builder MCP server and ships 8 workflow skills that route Claude to the right CLI / MCP / docs surface for token construction, review, simulation, and on-chain queries. Thin harness on top of the BitBadges chain binary + CLI — not a knowledge base.", + "version": "0.1.0", + "license": "CC-BY-NC-SA-4.0", + "repository": "https://github.com/BitBadges/bitbadges-plugin", + "homepage": "https://docs.bitbadges.io/for-developers/ai-agents/claude-code-plugin", + "author": { + "name": "BitBadges", + "email": "support@bitbadges.io", + "url": "https://bitbadges.io" + }, + "keywords": [ + "bitbadges", + "blockchain", + "cosmos", + "tokens", + "nft", + "smart-token", + "mcp", + "ai-agents" + ], + "category": "blockchain" + } + ] +} diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 4aa079d..165a890 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -12,22 +12,26 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Validate plugin.json is valid JSON - run: jq -e . .claude-plugin/plugin.json > /dev/null - - - name: Validate .mcp.json is valid JSON - run: jq -e . .mcp.json > /dev/null + - name: Validate JSON files + run: | + jq -e . .claude-plugin/plugin.json > /dev/null + jq -e . .claude-plugin/marketplace.json > /dev/null + jq -e . .mcp.json > /dev/null + jq -e . hooks/hooks.json > /dev/null - - name: Check required manifest fields + - name: Check plugin.json required fields run: | jq -e '.name and .version and .description' .claude-plugin/plugin.json > /dev/null - echo "Manifest has required fields" - - name: Check skill frontmatter + - name: Check marketplace.json required fields + run: | + jq -e '.name and .owner.name and (.plugins | length > 0) and (.plugins[0].name and .plugins[0].source)' .claude-plugin/marketplace.json > /dev/null + + - name: Check skill + command frontmatter run: | set -e missing=0 - for f in $(find skills -name SKILL.md 2>/dev/null); do + for f in $(find skills -name SKILL.md 2>/dev/null) $(find commands -name '*.md' 2>/dev/null); do if ! head -1 "$f" | grep -q '^---$'; then echo "Missing frontmatter: $f" missing=$((missing + 1)) @@ -38,7 +42,34 @@ jobs: fi done if [ "$missing" -gt 0 ]; then - echo "$missing skill(s) failed frontmatter check" + echo "$missing file(s) failed frontmatter check" exit 1 fi - echo "All skills have frontmatter" + echo "All skills + commands have frontmatter" + + - name: Check referenced scripts exist + are executable + run: | + set -e + for s in scripts/doctor.sh scripts/prewarm.sh; do + if [ ! -f "$s" ]; then echo "Missing: $s"; exit 1; fi + if [ ! -x "$s" ]; then echo "Not executable: $s"; exit 1; fi + bash -n "$s" + done + + - name: Check agent frontmatter + run: | + set -e + for f in $(find agents -name '*.md' 2>/dev/null); do + if ! head -1 "$f" | grep -q '^---$'; then + echo "Missing frontmatter: $f" + exit 1 + fi + if ! grep -q '^name:' "$f"; then + echo "Missing name: $f" + exit 1 + fi + if ! grep -q '^description:' "$f"; then + echo "Missing description: $f" + exit 1 + fi + done diff --git a/CHANGELOG.md b/CHANGELOG.md index c9e251c..5596d33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,3 +6,16 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th ### Added - Initial scaffolding: plugin manifest, MCP server registration, README, LICENSE. +- 8 skills, all hand-written as routing guides on top of the CLI / MCP / docs (no duplicated SDK content): + - `build` — meta-guide for constructing any token type. Routes Claude to `bitbadges-cli sdk skills ` for canonical instructions and the per-field MCP tools for construction. + - `review`, `simulate`, `explain` — pre-broadcast safety net. + - `query`, `address`, `claim` — runtime ops. + - `broadcast` — hard-railed live broadcast. +- 2 slash commands: `/bitbadges:setup`, `/bitbadges:status`. +- `bitbadges-builder` subagent definition for focused builder loops. +- `scripts/doctor.sh` — diagnostic script powering both slash commands. +- `scripts/prewarm.sh` + `hooks/hooks.json` — `SessionStart` hook that pre-warms the npx cache so the first MCP-tool call doesn't pay 5–15s of npm download. + +### Design + +The plugin is intentionally **a thin harness, not a knowledge base**. Token-type-specific instructions live in the SDK at `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts` and are surfaced to Claude on demand via `bitbadges-cli sdk skills `, the `get_skill_instructions` MCP tool, and the Gitbook pages at https://docs.bitbadges.io/x-tokenization/examples/skills/. The plugin's job is to teach Claude where to find them and how to compose them — not to ship 22 routing wrappers that just point at the same content. diff --git a/README.md b/README.md index 4f2b823..9ba42fa 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,53 @@ # BitBadges Plugin for Claude Code -A Claude Code plugin that auto-wires the BitBadges builder MCP server and ships curated skills for token creation, review, simulation, and on-chain queries. +A Claude Code plugin that auto-wires the BitBadges builder MCP server and teaches Claude how to leverage the BitBadges CLI + docs to build, review, simulate, and query tokens. -## Install +The plugin is a thin **harness on top of the CLI**. It does not redefine token types or duplicate skill content — every workflow ultimately routes to `bitbadges-cli` commands, the `bitbadges-builder` MCP, or the public docs at https://docs.bitbadges.io. Source of truth stays in the SDK; the plugin just makes Claude reach for the right tool at the right time. -``` -/plugin marketplace add BitBadges/bitbadges-plugin -/plugin install bitbadges -``` +## Prerequisites -That's it. After install, you have: +The BitBadges chain binary + CLI are the canonical way to interact with BitBadges. Install them first: -- **MCP tools** — `bitbadges-builder` registered automatically (no `claude mcp add` step). -- **~29 skills** — token creation (smart-token, fungible, NFT, subscription, vault, claim, quest, auction, …), review, simulate, explain, query, address, broadcast. -- **2 slash commands** — `/bitbadges:setup` and `/bitbadges:status`. +```sh +curl -fsSL https://install.bitbadges.io | sh +``` -The plugin uses `npx -y -p bitbadges bitbadges-builder` under the hood, so the latest published `bitbadges` npm package is fetched on first use. No separate install of the JS CLI is required. +This installs `bitbadgeschaind` (the chain binary) and `bitbadges-cli` (the JS CLI that exposes 104+ API routes plus the `bitbadges-builder` MCP server). This plugin is a Claude Code convenience layer on top of those — it does not replace them. -## What you can do without setup +Get an API key at [bitbadges.io/developer](https://bitbadges.io/developer) and configure it once: -The MCP server alone covers the vast majority of CC workflows: build a token, review a transaction, simulate a broadcast, query a collection, derive an address. None of these need the chain binary. +```sh +bitbadges-cli config set apiKey YOUR_KEY +``` -## What needs `/bitbadges:setup` +## Install the plugin -Local key management and live transaction broadcasts use the `bitbadgeschaind` chain binary, which is a separate Go binary. Run: +After the prerequisites above: ``` -/bitbadges:setup +/plugin marketplace add BitBadges/bitbadges-plugin +/plugin install bitbadges ``` -This walks through installing `bitbadgeschaind` via `https://install.bitbadges.io` (with consent prompt — never auto-pipes to sh) and configures your API key. +Then run `/bitbadges:setup` once to verify everything is wired and `/bitbadges:status` whenever you want a health check. + +## What the plugin adds + +- **MCP tools** — `bitbadges-builder` registered automatically (no separate `claude mcp add` step). Exposes 50+ session-based per-field token construction tools, queries, validation, review, and simulation. +- **8 skills** — guides that route Claude to the right CLI command, MCP tool, or docs page for each common BitBadges workflow: + - `build` — meta-guide for building any token type. Discovers via `bitbadges-cli sdk skills`, loads canonical instructions from the SDK, constructs via per-field MCP tools. + - `review`, `simulate`, `explain` — pre-broadcast safety net. Wraps `bitbadges-cli sdk review`, MCP `simulate_transaction`, and `bitbadges-cli sdk interpret-collection`. + - `query`, `address`, `claim` — runtime ops. Wraps the API routes, address derivations, and claim builder respectively. + - `broadcast` — hard-railed signer. Dry-run by default, explicit confirmation for live. +- **2 slash commands** — `/bitbadges:setup` (one-time prereq check + API key wiring) and `/bitbadges:status` (health check). +- **`bitbadges-builder` subagent** for focused builder loops. +- **SessionStart pre-warm** so the first MCP-tool call doesn't pay npx download latency. + +The skills don't duplicate token-type knowledge from the SDK. They tell Claude *where* to find that knowledge (CLI / MCP / Gitbook) and *how* to combine it. The full Gitbook docs at https://docs.bitbadges.io are also fair game — fetch what you need. + +## Fallback behavior + +If `bitbadges-cli` and `bitbadges-builder` aren't on your PATH (because you skipped the prerequisites), the plugin falls back to `npx -y -p bitbadges bitbadges-builder` for the MCP server. This works for read-only LLM workflows but is a degraded path — a globally installed CLI is faster, more reliable, and what `/bitbadges:setup` will recommend. ## API key diff --git a/agents/bitbadges-builder.md b/agents/bitbadges-builder.md new file mode 100644 index 0000000..329eae1 --- /dev/null +++ b/agents/bitbadges-builder.md @@ -0,0 +1,35 @@ +--- +name: bitbadges-builder +description: Specialized subagent for building, reviewing, and broadcasting BitBadges tokens. Use when the user asks for a focused builder loop — e.g. "build me a smart token end to end" — and you want isolation from the main conversation. +model: inherit +--- + +You are a BitBadges builder subagent. Your job is to take a token-creation or transaction-building task end to end: design → build → review → simulate → (optionally) broadcast. + +## Tool preference + +1. **MCP tools first.** The `bitbadges-builder` MCP server exposes 50+ tools for session management, token construction, review, simulation, and queries. Use `set_standards`, `set_invariants`, `add_approval`, `validate_transaction`, `review_collection`, `simulate_transaction`, `get_skill_instructions`, etc. directly — don't shell out unless MCP is unavailable. +2. **CLI fallback.** If an MCP tool isn't available or the user is doing something off the happy path (custom queries, address derivations not exposed via MCP), fall back to `bitbadges-cli` subcommands: `sdk`, `api`, `builder`, `config`. +3. **Chain binary last.** `bitbadgeschaind` is only for key management and live broadcasts. Default to dry-run; require explicit user confirmation for live broadcasts. + +## Workflow on a creation task + +1. Identify the token type or skill the user wants. Call `get_skill_instructions` with the matching skill id (e.g. `smart-token`, `subscription`, `crowdfund`) to load the canonical instructions. +2. Use the per-field session tools (`set_standards`, `set_invariants`, `add_alias_path`, `add_approval`, `set_permissions`, etc.) to construct the transaction step by step. Each call updates the session state. +3. `validate_transaction` after the full structure is built. Address every error, surface every warning to the user. +4. `review_collection` for an opinionated audit (foot-guns, reserved-symbol clashes, ordering issues). +5. `simulate_transaction` to dry-run. +6. Show the user the simulator output and ask explicitly before broadcasting. +7. If broadcasting locally, route through the chain binary (`bitbadgeschaind tx ...`); if remote, use the broadcast helpers in the CLI. + +## Always + +- Throw / surface errors over silent coercion. The BitBadges convention is "fix at the producer, don't band-aid the consumer". +- Confirm network (mainnet vs testnet) before any broadcast. +- Treat mnemonics, private keys, and unsigned transactions with the same care as the user's password — never log them as casual output. + +## Never + +- Never broadcast to mainnet without explicit user confirmation in the same turn. +- Never invent route paths or tool names — discover via `--help-json` or `tools/list`. +- Never skip simulate-then-review before a live broadcast. diff --git a/commands/setup.md b/commands/setup.md new file mode 100644 index 0000000..0f6d583 --- /dev/null +++ b/commands/setup.md @@ -0,0 +1,26 @@ +--- +description: One-time setup for the BitBadges plugin — checks prerequisites, configures the API key, and optionally installs the chain binary. +argument-hint: (no arguments) +--- + +# /bitbadges:setup + +Verifies that the BitBadges chain binary + CLI are installed (these are the canonical entrypoint — the plugin is a convenience layer on top) and that an API key is configured. Run this once after installing the plugin. + +The chain + CLI install is **the** entrypoint. The plugin's `npx`-based MCP fallback only exists as graceful degradation for users who haven't run the install one-liner yet. + +## What it does + +1. **Chain binary check (required).** If `bitbadgeschaind` is on PATH, print the version. If not, print the install one-liner (`curl -fsSL https://install.bitbadges.io | sh`) and ask for explicit consent before running it. Never auto-pipe `curl ... | sh` — show the command, wait for "yes". +2. **CLI check (required).** Same flow — if `bitbadges-cli` is on PATH, OK; otherwise the same one-liner installs both binaries together. The presence of `bitbadges-cli` globally also means the `bitbadges-builder` MCP bin is on PATH, which is faster and more reliable than the plugin's npx fallback. +3. **API key (required).** If `~/.bitbadges/config.json` already has an `apiKey`, use it — no prompt. The CLI config is canonical; both the CLI and the plugin read from there. Otherwise prompt for the key and write via `bitbadges-cli config set apiKey `. Source: https://bitbadges.io/developer. +4. **Migration check (optional).** If the user previously ran `claude mcp add bitbadges-builder ...` manually (user scope), that registration coexists with the plugin's `.mcp.json` entry and produces duplicate MCP servers. Detect it (`claude mcp list | grep bitbadges-builder`) and offer to run `claude mcp remove bitbadges-builder` to clean up. + +## Behavior summary for Claude + +- Run `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh --json` to enumerate current state. +- Walk steps 1–4 in order. The chain binary + CLI install is the FIRST thing — don't skip it on the assumption "MCP via npx is good enough". +- For each missing prerequisite, **show** the command but do not run it without explicit "yes" from the user. +- End with a one-line summary: "Ready to go" or "X step(s) skipped — re-run /bitbadges:setup when you want to address them". + +Do not store the API key in the plugin's `userConfig` keychain — write it to the CLI config so it works for everything: CLI, MCP, plugin, manual scripts. diff --git a/commands/status.md b/commands/status.md new file mode 100644 index 0000000..ca4ede0 --- /dev/null +++ b/commands/status.md @@ -0,0 +1,23 @@ +--- +description: Quick health check — chain binary version, JS CLI version, API connectivity, MCP server reachability, network selection. +argument-hint: (no arguments) +--- + +# /bitbadges:status + +A one-shot diagnostic. Runs `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh` and reports: + +- `bitbadgeschaind` version (or "not installed"). +- `bitbadges-cli` version (resolved via `npx bitbadges --version`). +- Active network (mainnet / testnet / local). +- API connectivity (`bitbadges-cli sdk status`). +- API key configured (yes/no, masked). +- MCP server `bitbadges-builder` is reachable. + +Output is human-readable by default. For machine-readable output, the underlying script also accepts `--json`, but slash commands invoke the human form. + +## When to use + +- After `/bitbadges:setup` to confirm everything's wired. +- When something stops working and you want to diagnose without running every command yourself. +- Before a long agent session as a smoke test. diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..abc2001 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/prewarm.sh", + "timeout": 30 + } + ] + } + ] + } +} diff --git a/scripts/doctor.sh b/scripts/doctor.sh new file mode 100755 index 0000000..68df85a --- /dev/null +++ b/scripts/doctor.sh @@ -0,0 +1,119 @@ +#!/usr/bin/env bash +# BitBadges plugin doctor — environment diagnostics for /bitbadges:setup and /bitbadges:status. +# +# Usage: +# ./doctor.sh Human-readable output +# ./doctor.sh --json Machine-readable JSON +# +# Exits 0 if all critical checks pass, 1 otherwise. "Critical" = JS CLI reachable +# and API key present. The chain binary is optional — most CC workflows don't +# need it. + +set -e + +OUTPUT_JSON=0 +if [ "${1:-}" = "--json" ]; then + OUTPUT_JSON=1 +fi + +# --- Detection --- + +chaind_path="" +chaind_version="" +if command -v bitbadgeschaind >/dev/null 2>&1; then + chaind_path="$(command -v bitbadgeschaind)" + chaind_version="$(bitbadgeschaind version 2>&1 | head -1 || echo unknown)" +fi + +cli_path="" +cli_version="" +if command -v bitbadges-cli >/dev/null 2>&1; then + cli_path="$(command -v bitbadges-cli)" + cli_version="$(bitbadges-cli --version 2>/dev/null || echo unknown)" +elif command -v npx >/dev/null 2>&1; then + # The plugin uses npx -y -p bitbadges; check that path works too. + cli_version="$(npx -y -p bitbadges bitbadges --version 2>/dev/null | tail -1 || echo unreachable)" + if [ "$cli_version" != "unreachable" ]; then + cli_path="(via npx)" + fi +fi + +api_key_set="no" +api_key_source="" +if [ -f "$HOME/.bitbadges/config.json" ]; then + if grep -q '"apiKey"' "$HOME/.bitbadges/config.json" 2>/dev/null; then + api_key_set="yes" + api_key_source="$HOME/.bitbadges/config.json" + fi +fi +if [ -n "${BITBADGES_API_KEY:-}" ]; then + api_key_set="yes" + api_key_source="${api_key_source:+$api_key_source + }BITBADGES_API_KEY env" +fi + +# Network: env var beats CLI config beats default. +network="${BITBADGES_NETWORK:-}" +if [ -z "$network" ] && [ -f "$HOME/.bitbadges/config.json" ]; then + network="$(grep -oE '"network":[[:space:]]*"[^"]*"' "$HOME/.bitbadges/config.json" 2>/dev/null | sed 's/.*"\([^"]*\)"/\1/' | head -1)" +fi +network="${network:-mainnet}" + +# API connectivity (only attempt if we have a CLI path). +api_status="skipped (no CLI)" +if [ -n "$cli_path" ] && [ "$api_key_set" = "yes" ]; then + if [ "$cli_path" = "(via npx)" ]; then + api_status="$(npx -y -p bitbadges bitbadges sdk status 2>&1 | tail -1 || echo error)" + else + api_status="$(bitbadges-cli sdk status 2>&1 | tail -1 || echo error)" + fi +fi + +# Critical = CLI reachable + API key set. +critical_ok="yes" +[ -z "$cli_path" ] && critical_ok="no" +[ "$api_key_set" = "no" ] && critical_ok="no" + +# --- Output --- + +if [ "$OUTPUT_JSON" -eq 1 ]; then + cat </dev/null 2>&1; then + exit 0 +fi + +if [ -n "${DEBUG_BB_PREWARM:-}" ]; then + npx -y -p bitbadges bitbadges --version +else + npx -y -p bitbadges bitbadges --version >/dev/null 2>&1 || true +fi + +exit 0 diff --git a/skills/address/SKILL.md b/skills/address/SKILL.md new file mode 100644 index 0000000..4e0a59b --- /dev/null +++ b/skills/address/SKILL.md @@ -0,0 +1,36 @@ +--- +description: Convert, validate, or derive BitBadges addresses — cosmos↔EVM conversion, IBC backing, wrapper, mint-escrow, alias address derivations. +--- + +# Address + +BitBadges runs on a Cosmos chain with EVM compatibility, so addresses come in two formats and several derived forms. This skill anchors all six common operations so the user doesn't get them wrong. + +## Conversion + +```bash +bitbadges-cli sdk address convert
--to +bitbadges-cli sdk address validate
+``` + +`bb1...` ↔ `0x...` is deterministic — same key, two encodings. The CLI handles the bech32/hex math. + +## Derived addresses + +| Need | Command | +|---|---| +| Backing address for an IBC denom (smart-token deposits) | `bitbadges-cli sdk alias for-ibc-backing ` | +| Wrapper address for a collection | `bitbadges-cli sdk alias for-wrapper ` | +| Mint-escrow address for a collection | `bitbadges-cli sdk alias for-mint-escrow ` | + +These are protocol-controlled addresses with auto-set approvals. Don't try to write to them directly — use the corresponding flow (IBC backing, mint, etc.). + +## Failure modes + +- "Address is not bech32-valid" — likely a typo or wrong prefix; bb1 = BitBadges, cosmos1 = generic Cosmos. +- "Collection doesn't exist" when deriving wrapper/mint-escrow — confirm the collection ID and network. + +## Don't + +- Don't compute address derivations by hand. The CLI is the source of truth. +- Don't confuse `bb1...` with `cosmos1...` — they are different chains. diff --git a/skills/broadcast/SKILL.md b/skills/broadcast/SKILL.md new file mode 100644 index 0000000..f107e9b --- /dev/null +++ b/skills/broadcast/SKILL.md @@ -0,0 +1,49 @@ +--- +description: Sign and broadcast a BitBadges transaction. Requires the chain binary and a key. Defaults to dry-run; --live must be explicitly requested. +--- + +# Broadcast + +This is the only skill that touches money. Treat it as on-rails, not LLM-discovered. + +## Hard requirements + +- `bitbadgeschaind` is installed locally (`bb-doctor` will tell you). +- A key is configured (`bitbadgeschaind keys list`). +- The transaction has been **simulated and reviewed** in the same session. + +If any of those is missing, stop and route to `/bitbadges:setup` or the relevant skill. + +## Default: dry-run + +```bash +bitbadgeschaind tx --from --dry-run +``` + +Always dry-run first. Show the user the simulator output. Wait for explicit "yes, broadcast for real" before going live. + +## Live broadcast (explicit user confirmation required) + +```bash +bitbadgeschaind tx --from -y +``` + +Network flags: +- Mainnet (default): no flag +- Testnet: `--node https://rpc-testnet.bitbadges.io --chain-id bitbadges-1-testnet` + +(Or use `bitbadges-cli`'s `--testnet` flag and the equivalent JSON-RPC route if not using the chain binary directly.) + +## Failure modes + +- "bitbadgeschaind: command not found" — route to `/bitbadges:setup`. +- "key not found" — list available keys and ask the user which one to use. +- "insufficient fees" — chain binary will print the required minimum; bump and retry. +- "out of gas" — let the binary auto-estimate (`--gas auto`) and retry, or have the user set a higher cap. + +## Hard don'ts + +- Don't broadcast to mainnet without explicit user confirmation in the same turn. +- Don't broadcast a transaction that hasn't been simulated. +- Don't loop a failing broadcast more than twice — stop and report rather than chewing through fees. +- Don't expose mnemonic, private key, or unsigned transaction body to the user as casual log output. diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md new file mode 100644 index 0000000..9580bb8 --- /dev/null +++ b/skills/build/SKILL.md @@ -0,0 +1,64 @@ +--- +description: Build any kind of BitBadges token (smart-token, fungible, NFT, subscription, vault, claim, quest, auction, payment, crowdfund, prediction-market, ...). Discover the right type via the CLI, load canonical instructions from the SDK, construct via per-field MCP tools. +--- + +# Build a BitBadges token + +Use this skill any time the user wants to create a BitBadges collection or token of any kind. **Don't make up token-type-specific knowledge from training data** — the SDK changes constantly. Instead, discover and load the canonical instructions, then construct via the per-field MCP tools. + +The plugin does not redefine token types here. They live in the SDK and are surfaced through the CLI's `sdk skills` command, the MCP's `get_skill_instructions` tool, and the Gitbook pages. This skill teaches Claude to use those. + +## Step 1 — Discover the available token type + +```sh +bitbadges-cli sdk skills # list every available skill (id, name, category, description) +bitbadges-cli sdk skills # load the canonical instructions for one skill +``` + +If the user describes their goal but doesn't name a token type, list the catalog first and pick by category. Categories: `token-type`, `standard`, `approval`, `feature`, `advanced`. + +Web reference: every skill is also rendered at `https://docs.bitbadges.io/x-tokenization/examples/skills/` — fetch with WebFetch if a CLI run isn't viable. + +## Step 2 — Load the canonical instructions + +The instructions are the source of truth — required fields, approval ordering, foot-guns, reference collection IDs. Load them, don't reconstruct them: + +- **MCP (preferred in Claude Code):** call `get_skill_instructions` with `id: ""`. +- **CLI:** `bitbadges-cli sdk skills ` +- **Web docs:** `https://docs.bitbadges.io/x-tokenization/examples/skills/` + +## Step 3 — Construct the transaction + +Use the MCP per-field session tools. Each call sets one field on a session-scoped transaction so you can build incrementally and inspect along the way: + +`set_standards`, `set_invariants`, `add_alias_path`, `add_approval`, `set_permissions`, `set_valid_token_ids`, `set_collection_metadata`, … (full list via the MCP server's `tools/list`). + +If you need an address derivation, dial the `address` skill. If you need claim setup on top of an approval, dial `claim`. + +## Step 4 — Validate, review, simulate + +Before the user even thinks about broadcasting: + +1. `validate_transaction` (MCP) — fix every error. +2. `review_collection` (MCP) — opinionated audit. Surface every warning explicitly. +3. `simulate_transaction` (MCP) — see what would happen on-chain. Show the user the simulator output. + +Only then route to the `broadcast` skill, which has its own hard rails. + +## Going deeper + +The CLI's `sdk docs` command surfaces the full Gitbook docs from your terminal. Use it when a skill instruction references a concept you need to look up: + +```sh +bitbadges-cli sdk docs all # dump the entire docs corpus +bitbadges-cli sdk docs # specific page, e.g. learn/approvals +``` + +You also have full access to the public docs at `https://docs.bitbadges.io` if you need to fetch a page directly. Fetch only what you need; don't dump entire sections into the context for fun. + +## Don't + +- Don't manufacture token-type knowledge from training data — load from the SDK every time. The schema and required fields change. +- Don't construct the JSON by hand when MCP per-field tools exist for it. They validate as they go. +- Don't skip validate / review / simulate before routing to `broadcast`. +- Don't broadcast for the user — that's the `broadcast` skill's job and it requires explicit user confirmation in the same turn. diff --git a/skills/claim/SKILL.md b/skills/claim/SKILL.md new file mode 100644 index 0000000..8860ff0 --- /dev/null +++ b/skills/claim/SKILL.md @@ -0,0 +1,43 @@ +--- +description: Build or audit a BitBadges claim — code-gated, password-gated, whitelist, open, or token-gated. Use when the user wants users to redeem something on a claim page. +--- + +# Claim + +A BitBadges "claim" is a redemption page where users (gated however the manager chooses) can claim tokens, perform a transfer, or trigger a payment. This skill handles building new claims and auditing existing ones. + +## Build + +Use the `build_claim` MCP tool with the desired plugins (gating modes) and approval target. CLI fallback for offline preview: + +```bash +bitbadges-cli builder claim build --plugins , --target +``` + +## Common gating modes (plugins) + +| Mode | Plugin id | Use when | +|---|---|---| +| Whitelist (address list) | `whitelist` | Specific addresses pre-approved | +| Password | `password` | Single shared secret | +| Codes | `codes` | One-time-use codes (good for events) | +| Open | (none) | Anyone can claim | +| Token-gated | `must-own-tokens` | Holders of another collection only | + +## Audit existing + +```bash +bitbadges-cli api claims get-claim +``` + +Then review for: overlapping plugins (e.g. password + open), expired time windows, max-uses set or unset, and whether the underlying approval still has supply. + +## Failure modes + +- Mismatched plugin ids — the CLI / MCP will reject; confirm against `bitbadges-cli api --help-json` if unsure. +- Gating mode that doesn't compose with the chosen approval (e.g. open claim against a 1-use approval). + +## Don't + +- Don't build a claim against an approval that doesn't exist yet — the approval has to be created first via the underlying token-creation skill. +- Don't share password/codes back to the user as plain log lines — call them out as sensitive. diff --git a/skills/explain/SKILL.md b/skills/explain/SKILL.md new file mode 100644 index 0000000..d5a75d1 --- /dev/null +++ b/skills/explain/SKILL.md @@ -0,0 +1,41 @@ +--- +description: Explain in plain English what a BitBadges collection or transaction does. Audience-aware — pick user, developer, or auditor framing. +--- + +# Explain + +Use when the user wants natural-language understanding rather than raw JSON. + +## When to invoke + +- "What does collection X do?" +- "Explain this transaction to me." +- The user is writing audit notes, end-user copy, or a code-review comment about a BitBadges collection. + +## What to do + +**Live collection (numeric ID):** + +Call the `explain_collection` MCP tool with `collectionId: ""` and an `audience` of `user`, `developer`, or `auditor`. CLI fallback: + +```bash +bitbadges-cli sdk interpret-collection --audience +``` + +**Transaction file:** + +```bash +bitbadges-cli sdk interpret-tx @.json --audience +``` + +## Audience selection + +- `user` — non-technical end-user. Use for marketing copy, claim-page descriptions. +- `developer` — someone building an integration. Highlight permissions, approvals, supply curves. +- `auditor` — someone reviewing for safety. Highlight foot-guns, irreversible permissions, manager privileges, anything custodial. + +When unsure, ask the user which audience or default to `developer`. + +## Don't + +- Don't make up behavior the JSON doesn't support. If a field is missing or set to a default, say so explicitly rather than inferring. diff --git a/skills/query/SKILL.md b/skills/query/SKILL.md new file mode 100644 index 0000000..60537f0 --- /dev/null +++ b/skills/query/SKILL.md @@ -0,0 +1,45 @@ +--- +description: Query BitBadges collections, balances, accounts, claims, addresses, and any of the 104+ API routes. Discovers routes via --help-json instead of guessing. +--- + +# Query + +Use this skill any time the user wants on-chain or off-chain BitBadges data — collection details, balances, account profiles, claim status, transfer history, or any other API route. + +## Discovery first, then query + +LLMs frequently hallucinate route paths. The CLI exposes the full API tree as JSON — always discover, then query. + +```bash +bitbadges-cli api --help-json +bitbadges-cli api --help-json # e.g. tokens, accounts, claims, addresses +``` + +The `--help-json` output is the source of truth for routes and parameters. Read it before calling a route you're not 100% sure exists. + +## Common queries + +| Need | Command | +|---|---| +| Collection details | `bitbadges-cli api tokens get-collection ` | +| Balances for an address | `bitbadges-cli api tokens get-balance
` | +| Account profile | `bitbadges-cli api accounts get-account
` | +| Claim status | `bitbadges-cli api claims get-claim ` | +| Address list contents | `bitbadges-cli api address-lists get-list ` | + +Or use the MCP fast-paths: `query_collection`, `query_balance`, `verify_ownership`. + +## Networks + +Add `--testnet` to any command to hit testnet. Add `--local` for `http://localhost:3001`. Default is mainnet. + +## Failure modes + +- 401/403 — `BITBADGES_API_KEY` not set or wrong network. Route to `/bitbadges:setup`. +- 404 on a collection ID — confirm the ID and network with the user (a testnet collection won't appear on mainnet). +- Pagination — many routes paginate; check the response for `nextCursor` and ask the user if they want subsequent pages. + +## Don't + +- Don't invent route paths. If `--help-json` doesn't list it, it doesn't exist. +- Don't dump full unfiltered API responses on the user — summarize, then offer the raw JSON if they want it. diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md new file mode 100644 index 0000000..dd23d0a --- /dev/null +++ b/skills/review/SKILL.md @@ -0,0 +1,45 @@ +--- +description: Review a BitBadges transaction file or live collection for correctness, standards compliance, approval ordering, and UX issues before broadcasting. +--- + +# Review + +Use this skill any time the user has built a BitBadges transaction or wants a second opinion on an existing on-chain collection. + +## When to invoke + +- The user has a `tx.json` or similar transaction file on disk and wants it reviewed. +- The user mentions a collection ID (e.g. "audit collection 142", "is collection 99 set up correctly?"). +- After any `bb-create-*` skill produces a transaction — always review before broadcasting. + +## What to do + +**Transaction file review (input is a path):** + +```bash +bitbadges-cli sdk review @ +``` + +The CLI accepts `@file.json` syntax for path inputs. JSON output includes parsed warnings, errors, and suggestions. + +**Live collection review (input is a numeric ID or a collection ID string):** + +Call the `review_collection` MCP tool with `collectionId: ""`. Falls back to `bitbadges-cli api tokens get-collection ` + manual inspection if MCP isn't available. + +## What good output looks like + +- Standards compliance (Smart Token, Subscription, Tradable, etc. — required fields present, no contradictions). +- Approval ordering — `mustPrioritize: true` on the right approvals; no shadowing. +- Permissions — not over-restricted; `canArchiveCollection` and similar irreversible flags reviewed. +- Metadata — placeholders are unset before broadcast; alias paths sane. +- Foot-guns — `fromListId: "Mint"` on smart tokens, reused reserved symbols (USDC/ATOM/BADGE), missing unbacking approvals, wrong decimals on alias paths. + +## Failure modes + +- Input is a directory or stdin — the CLI accepts `-` for stdin and `@dir/file.json` for paths; if both fail, ask the user for the actual file path. +- `BITBADGES_API_KEY` not set when reviewing a live collection — surface this clearly and route to `/bitbadges:setup`. + +## Don't + +- Don't broadcast after review without explicit user confirmation. Review is read-only. +- Don't auto-fix what the review surfaces — ask the user what to address. Per BitBadges convention, throws beat silent coercions. diff --git a/skills/simulate/SKILL.md b/skills/simulate/SKILL.md new file mode 100644 index 0000000..6607c63 --- /dev/null +++ b/skills/simulate/SKILL.md @@ -0,0 +1,48 @@ +--- +description: Dry-run a BitBadges transaction without broadcasting. Returns parsed events, balance diffs per address, and any errors that would surface on-chain. +--- + +# Simulate + +Always prefer simulate-first over broadcast-and-see. Use this skill before any `bb-broadcast` invocation, and any time the user wants to know "what would happen if I sent this tx". + +## When to invoke + +- The user is about to broadcast a transaction. +- The user asks "what does this tx do" or "will this work". +- After `bb-review` flags concerns and the user wants to see runtime behavior. + +## What to do + +**Via MCP (preferred in Claude Code):** + +Call the `simulate_transaction` MCP tool with the transaction object. + +**Via CLI:** + +```bash +bitbadges-cli builder simulate @ +``` + +Or pipe a transaction via stdin: + +```bash +cat tx.json | bitbadges-cli builder simulate - +``` + +## What good output looks like + +- A list of resulting events (token mints, transfers, approvals consumed). +- Per-address balance diffs (before / after). +- Any errors that the chain would have raised, surfaced as plain English. + +## Failure modes + +- Missing `creator` address on the transaction — the simulator can't run without one. Prompt the user to add it. +- `BITBADGES_API_KEY` not set — route to `/bitbadges:setup`. +- Transaction references a nonexistent collection — surface the ID that wasn't found. + +## Don't + +- Don't claim a simulation result equals the broadcast result. Edge cases (block timing, races, fee spikes) can still bite. +- Don't simulate then broadcast in one step without explicit user confirmation between the two.