From fde921545dc8ae5b9fff75a3395c99e2f233d13c Mon Sep 17 00:00:00 2001 From: Trevor Miller Date: Sun, 26 Apr 2026 08:31:50 -0400 Subject: [PATCH 1/4] Add skills, slash commands, agent, doctor + pre-warm scripts, SessionStart hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plugin v0.1 content: - 22 generated SKILL.md files (one per SDK SKILL_INSTRUCTIONS id) — thin routing wrappers; substance fetched at invoke time via the bitbadges-builder MCP tool get_skill_instructions or `bitbadges-cli sdk skills `. Generated by bitbadgesjs-sdk/scripts/gen-llm-mirrors.ts (separate PR). - 7 hand-written operational skills covering the workflows that don't map to a SDK skill id: review, simulate, explain, query, address, claim, broadcast. Each is on-rails — explicit failure modes, hard don'ts, and clear routing back to /bitbadges:setup when prerequisites are missing. - 2 slash commands: /bitbadges:setup — one-time prereq check + API key wiring. Reads existing ~/.bitbadges/config.json (CLI is canonical) before prompting. Never auto-pipes curl|sh. /bitbadges:status — quick health check via doctor.sh. - agents/bitbadges-builder.md — subagent definition for focused builder loops; primed to reach for MCP tools first, fall back to CLI, only touch the chain binary for live broadcasts. - scripts/doctor.sh — environment diagnostic. Powers both slash commands. Detects chain binary, CLI (or via npx), API key, network, and API connectivity. JSON or human output. - scripts/prewarm.sh + hooks/hooks.json — SessionStart hook that silently warms the npx cache for the bitbadges package so the first MCP-tool call doesn't pay 5–15s download. Best-effort: exits 0 if npx is missing or network is offline. Per backlog #0342 in bitbadges-autopilot. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 6 ++ agents/bitbadges-builder.md | 35 +++++++++ commands/setup.md | 26 +++++++ commands/status.md | 23 ++++++ hooks/hooks.json | 15 ++++ scripts/doctor.sh | 119 ++++++++++++++++++++++++++++++ scripts/prewarm.sh | 22 ++++++ skills/address-list/SKILL.md | 33 +++++++++ skills/address/SKILL.md | 36 +++++++++ skills/auction/SKILL.md | 33 +++++++++ skills/auto-mint/SKILL.md | 33 +++++++++ skills/bb-402/SKILL.md | 33 +++++++++ skills/bounty/SKILL.md | 33 +++++++++ skills/broadcast/SKILL.md | 49 ++++++++++++ skills/burnable/SKILL.md | 33 +++++++++ skills/claim/SKILL.md | 43 +++++++++++ skills/credit-token/SKILL.md | 36 +++++++++ skills/crowdfund/SKILL.md | 33 +++++++++ skills/custom-2fa/SKILL.md | 32 ++++++++ skills/explain/SKILL.md | 41 ++++++++++ skills/fungible-token/SKILL.md | 32 ++++++++ skills/immutability/SKILL.md | 33 +++++++++ skills/liquidity-pools/SKILL.md | 31 ++++++++ skills/minting/SKILL.md | 33 +++++++++ skills/multi-sig-voting/SKILL.md | 33 +++++++++ skills/nft-collection/SKILL.md | 33 +++++++++ skills/payment-protocol/SKILL.md | 33 +++++++++ skills/prediction-market/SKILL.md | 33 +++++++++ skills/product-catalog/SKILL.md | 33 +++++++++ skills/query/SKILL.md | 45 +++++++++++ skills/quest/SKILL.md | 33 +++++++++ skills/review/SKILL.md | 45 +++++++++++ skills/simulate/SKILL.md | 48 ++++++++++++ skills/smart-token/SKILL.md | 33 +++++++++ skills/subscription/SKILL.md | 33 +++++++++ skills/tradable/SKILL.md | 33 +++++++++ 36 files changed, 1278 insertions(+) create mode 100644 agents/bitbadges-builder.md create mode 100644 commands/setup.md create mode 100644 commands/status.md create mode 100644 hooks/hooks.json create mode 100755 scripts/doctor.sh create mode 100755 scripts/prewarm.sh create mode 100644 skills/address-list/SKILL.md create mode 100644 skills/address/SKILL.md create mode 100644 skills/auction/SKILL.md create mode 100644 skills/auto-mint/SKILL.md create mode 100644 skills/bb-402/SKILL.md create mode 100644 skills/bounty/SKILL.md create mode 100644 skills/broadcast/SKILL.md create mode 100644 skills/burnable/SKILL.md create mode 100644 skills/claim/SKILL.md create mode 100644 skills/credit-token/SKILL.md create mode 100644 skills/crowdfund/SKILL.md create mode 100644 skills/custom-2fa/SKILL.md create mode 100644 skills/explain/SKILL.md create mode 100644 skills/fungible-token/SKILL.md create mode 100644 skills/immutability/SKILL.md create mode 100644 skills/liquidity-pools/SKILL.md create mode 100644 skills/minting/SKILL.md create mode 100644 skills/multi-sig-voting/SKILL.md create mode 100644 skills/nft-collection/SKILL.md create mode 100644 skills/payment-protocol/SKILL.md create mode 100644 skills/prediction-market/SKILL.md create mode 100644 skills/product-catalog/SKILL.md create mode 100644 skills/query/SKILL.md create mode 100644 skills/quest/SKILL.md create mode 100644 skills/review/SKILL.md create mode 100644 skills/simulate/SKILL.md create mode 100644 skills/smart-token/SKILL.md create mode 100644 skills/subscription/SKILL.md create mode 100644 skills/tradable/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c9e251c..72e5a75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,3 +6,9 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th ### Added - Initial scaffolding: plugin manifest, MCP server registration, README, LICENSE. +- 22 generated SKILL.md files (one per SDK `SKILL_INSTRUCTIONS` id), produced by the SDK's `gen-llm-mirrors` generator. Source of truth stays in `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts`. +- 7 hand-written operational skills: `review`, `simulate`, `explain`, `query`, `address`, `claim`, `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. 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..2d6d09b --- /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 + +Run this once after installing the plugin. It does four things: + +1. **Checks the chain binary.** If `bitbadgeschaind` is on PATH, prints the version. If not, prints the install one-liner (`curl -fsSL https://install.bitbadges.io | sh`) and asks for explicit consent before running it. +2. **Checks the JS CLI.** If `bitbadges-cli` is reachable (or `npx bitbadges --version` works), reports OK. If not, suggests the same one-liner. +3. **Reads existing API key.** If `~/.bitbadges/config.json` already has an `apiKey`, uses that — no prompt. The CLI config is canonical; the plugin reads from it. +4. **Otherwise prompts for API key** and writes it via `bitbadges-cli config set apiKey ` so both the CLI and the plugin pick it up. Sources: get an API key at https://bitbadges.io/developer. + +5. **Migration check.** 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 + +When the user runs `/bitbadges:setup`: + +- Run `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh --json` to enumerate the current state. +- Walk the four checks above in order. +- For each missing prerequisite, **show** the command but do not run it without an explicit "yes" from the user. Never auto-pipe `curl ... | sh`. +- 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 (`bitbadges-cli config set apiKey `) 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-list/SKILL.md b/skills/address-list/SKILL.md new file mode 100644 index 0000000..25b186f --- /dev/null +++ b/skills/address-list/SKILL.md @@ -0,0 +1,33 @@ +--- +description: On-chain address list where membership = owning x1 of token ID 1. Manager can add/remove addresses. +--- + + + +# Address List + +On-chain address list where membership = owning x1 of token ID 1. Manager can add/remove addresses. + +## When to use this skill + +Required standards: ["Address List"] + +- validTokenIds: MUST be exactly [{ "start": "1", "end": "1" }] +- TWO collection approvals required with EXACT approvalIds (frontend depends on these): + 1. "manager-add": fromListId "Mint", toListId "All", initiatedByListId = creator. Mints token to add address. + 2. "manager-remove": fromListId "All", toListId burn address (bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqs7gvmv), initiatedByListId = creator. Burns token to remove address. +- BOTH approvals MUST have overridesFromOutgoingApprovals: true +- NO peer-to-peer transfer approval — only manager can modify the list + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "address-list"`. +- **CLI**: `bitbadges-cli sdk skills address-list` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/address-list + +## Category + +`token-type` + 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/auction/SKILL.md b/skills/auction/SKILL.md new file mode 100644 index 0000000..1544597 --- /dev/null +++ b/skills/auction/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Single-item auction with intent-based bidding. Seller mints NFT directly to the winning bidder during the accept window. +--- + + + +# Auction + +Single-item auction with intent-based bidding. Seller mints NFT directly to the winning bidder during the accept window. + +## When to use this skill + +Required standards: ["Auction"] + +- 1 token ID (the auctioned item) +- 2 collection-level approvals: mint-to-winner (combines mint + accept), burn (cleanup) +- Mint-to-winner: seller mints NFT directly to winning bidder during accept window (bidDeadline → bidDeadline + acceptWindow) +- No separate mint-at-creation step — token doesn't exist until seller accepts a bid +- Burn: anyone can burn token to burn address (permanent cleanup) +- Bidding via user-level outgoing approval intents (not collection approvals) + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "auction"`. +- **CLI**: `bitbadges-cli sdk skills auction` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/auction + +## Category + +`token-type` + diff --git a/skills/auto-mint/SKILL.md b/skills/auto-mint/SKILL.md new file mode 100644 index 0000000..583b0a5 --- /dev/null +++ b/skills/auto-mint/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Mint and distribute tokens to recipients at collection creation time using MsgTransferTokens +--- + + + +# Auto-Mint + +Mint and distribute tokens to recipients at collection creation time using MsgTransferTokens + +## When to use this skill + +Post-creation minting — adds MsgTransferTokens messages to the transaction so tokens are distributed immediately after collection creation. + +- Transaction can contain MsgUniversalUpdateCollection PLUS one or more MsgTransferTokens messages +- All transfer messages use collectionId: "0" to reference the just-created collection +- prioritizedApprovals MUST always be specified (use [] if none needed) +- from: "Mint" for minting new tokens, bb1... address for peer-to-peer transfers +- The signing user (creator) is the initiator — collection must have an approval allowing this +- All numbers as strings — "1" not 1 + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "auto-mint"`. +- **CLI**: `bitbadges-cli sdk skills auto-mint` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/auto-mint + +## Category + +`feature` + diff --git a/skills/bb-402/SKILL.md b/skills/bb-402/SKILL.md new file mode 100644 index 0000000..5c39846 --- /dev/null +++ b/skills/bb-402/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Token-gated access protocol where ownership of specific badges grants API/resource access +--- + + + +# BB-402 Token-Gated Access + +Token-gated access protocol where ownership of specific badges grants API/resource access + +## When to use this skill + +Protocol for token-gated access to APIs/resources using HTTP 402 Payment Required. + +- Flow: client requests resource -> server returns 402 + required badge criteria -> client proves ownership -> server validates via BitBadges API +- ownershipRequirements: use $and for "must have all", $or for "must have any" +- mustOwnAmounts: { start: 1, end: 1 } = must own at least 1 +- mustOwnAmounts: { start: 0, end: 0 } = must NOT own (exclusion) +- Tiered access: different token IDs = different access levels +- Time-bounded access: combine ownershipTimes with subscription tokens + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "bb-402"`. +- **CLI**: `bitbadges-cli sdk skills bb-402` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/bb-402 + +## Category + +`feature` + diff --git a/skills/bounty/SKILL.md b/skills/bounty/SKILL.md new file mode 100644 index 0000000..8cc2ebe --- /dev/null +++ b/skills/bounty/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Escrow-based bounty with verifier arbitration. Submitter escrows coins, verifier accepts (pays recipient) or denies (refunds submitter). Expires if no decision. +--- + + + +# Bounty + +Escrow-based bounty with verifier arbitration. Submitter escrows coins, verifier accepts (pays recipient) or denies (refunds submitter). Expires if no decision. + +## When to use this skill + +Required standards: ["Bounty"] + +- 1 token ID (vehicle for approval engine — minted directly to burn) +- 3 collection-level approvals: accept, deny, expire +- Each approval: Mint → burn 1x token ID 1, triggers coinTransfer as side effect +- Verifier decides outcome via MsgCastVote +- Escrow pre-funded at creation via mintEscrowCoinsToTransfer +- Fixed bounty amount, no amount scaling + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "bounty"`. +- **CLI**: `bitbadges-cli sdk skills bounty` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/bounty + +## Category + +`token-type` + 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/burnable/SKILL.md b/skills/burnable/SKILL.md new file mode 100644 index 0000000..3b9b9e8 --- /dev/null +++ b/skills/burnable/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Allow token holders to burn tokens by sending them to the burn address, permanently removing them from circulation +--- + + + +# Burnable + +Allow token holders to burn tokens by sending them to the burn address, permanently removing them from circulation + +## When to use this skill + +Allows holders to permanently destroy tokens by sending to burn address. + +- Burn address: bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqs7gvmv (ETH null address in BitBadges format) +- Approval structure: fromListId: "!Mint", toListId: burn address +- overridesToIncomingApprovals: true (burn address has no user-level incoming approvals) +- approvalId: "burnable-approval" (standard ID used by frontend to detect burnability) +- All amounts/transfers set to "0" (unlimited) +- Additive: sits alongside other collection approvals + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "burnable"`. +- **CLI**: `bitbadges-cli sdk skills burnable` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/burnable + +## Category + +`approval` + 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/credit-token/SKILL.md b/skills/credit-token/SKILL.md new file mode 100644 index 0000000..5910214 --- /dev/null +++ b/skills/credit-token/SKILL.md @@ -0,0 +1,36 @@ +--- +description: Increment-only, non-transferable credit token purchased with any ICS20 denom. Users pay X of a denom and receive Y tokens as credits/proof of payment. For a 1:1 backed token with on-chain transferability, use the Smart Token standard inste… +--- + + + +# Credit Token + +Increment-only, non-transferable credit token purchased with any ICS20 denom. Users pay X of a denom and receive Y tokens as credits/proof of payment. For a 1:1 backed token with on-chain transferability, use the Smart Token standard instead. + +## When to use this skill + +Required standards: ["Credit Token"] + +- Increment-only, non-transferable (soulbound) fungible token purchased with ICS20 denom +- validTokenIds: [{ "start": "1", "end": "1" }] (single token ID) +- ONE Mint approval with approvalId "credit-scaled" using allowAmountScaling (single scaled approval supersedes the legacy 8-10 tier approach; legacy tiers still supported for backward compat but deprecated) +- Lock canUpdateCollectionApprovals (empty array = frozen) +- defaultBalances: autoApproveAllIncomingTransfers: true, autoApproveSelfInitiatedOutgoingTransfers: true, autoApproveSelfInitiatedIncomingTransfers: true +- Credit-scaled approval: overridesFromOutgoingApprovals: true, mustPrioritize: true, coinTransfers[0].coins[0].amount = "1" (micro-payment unit) + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "credit-token"`. +- **CLI**: `bitbadges-cli sdk skills credit-token` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/credit-token + +## Category + +`token-type` + +## Reference collections + +- [Collection 23](https://bitbadges.io/collections/23) diff --git a/skills/crowdfund/SKILL.md b/skills/crowdfund/SKILL.md new file mode 100644 index 0000000..925564f --- /dev/null +++ b/skills/crowdfund/SKILL.md @@ -0,0 +1,33 @@ +--- +description: On-chain crowdfunding with goal tracking via mustOwnTokens. Contributors deposit funds, receive refund tokens. Crowdfunder withdraws if goal met, contributors refund if not. +--- + + + +# Crowdfund + +On-chain crowdfunding with goal tracking via mustOwnTokens. Contributors deposit funds, receive refund tokens. Crowdfunder withdraws if goal met, contributors refund if not. + +## When to use this skill + +Required standards: ["Crowdfund"] + +- 2 token IDs: Token 1 = Refund token (contributor holds), Token 2 = Progress token (crowdfunder accumulates) +- 4 collection-level approvals: deposit-refund, deposit-progress, success (withdraw), refund +- Contributors deposit coins → receive Token 1 (refund token). Paired approval mints Token 2 to crowdfunder (progress tracking). +- Success: crowdfunder withdraws if mustOwnTokens confirms they hold >= goal of Token 2 (collectionId: 0 = self-reference) +- Refund: after deadline, contributors burn Token 1 → escrow pays them back (only if goal NOT met via mustOwnTokens check) +- allowAmountScaling: true on ALL 4 approvals (contributors choose deposit size, everything scales proportionally) + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "crowdfund"`. +- **CLI**: `bitbadges-cli sdk skills crowdfund` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/crowdfund + +## Category + +`token-type` + diff --git a/skills/custom-2fa/SKILL.md b/skills/custom-2fa/SKILL.md new file mode 100644 index 0000000..14daac5 --- /dev/null +++ b/skills/custom-2fa/SKILL.md @@ -0,0 +1,32 @@ +--- +description: Two-factor authentication for transfers using a secondary approval address +--- + + + +# Custom 2FA + +Two-factor authentication for transfers using a secondary approval address + +## When to use this skill + +Required standards: ["Custom-2FA"] + +- autoDeletionOptions.allowPurgeIfExpired: MUST be true +- Approval name MUST contain "Custom 2FA" +- Use time-dependent ownershipTimes in MsgTransferTokens (not forever) +- Calculate timestamps: current time + expiration duration (milliseconds since epoch) +- Tokens automatically expire and can be purged after expiration + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "custom-2fa"`. +- **CLI**: `bitbadges-cli sdk skills custom-2fa` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/custom-2fa + +## Category + +`token-type` + 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/fungible-token/SKILL.md b/skills/fungible-token/SKILL.md new file mode 100644 index 0000000..16df1d4 --- /dev/null +++ b/skills/fungible-token/SKILL.md @@ -0,0 +1,32 @@ +--- +description: Simple fungible token with fixed or unlimited supply and configurable mint/transfer approvals +--- + + + +# Fungible Token + +Simple fungible token with fixed or unlimited supply and configurable mint/transfer approvals + +## When to use this skill + +Required standards: ["Fungible Tokens"] + +- validTokenIds: MUST be exactly [{ "start": "1", "end": "1" }] (single token ID) +- All tokens share the same token ID (1), making them interchangeable +- Amount field in transfers determines quantity +- Token metadata must reference token ID 1 +- Ownership times typically forever: [{ "start": "1", "end": "18446744073709551615" }] + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "fungible-token"`. +- **CLI**: `bitbadges-cli sdk skills fungible-token` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/fungible-token + +## Category + +`token-type` + diff --git a/skills/immutability/SKILL.md b/skills/immutability/SKILL.md new file mode 100644 index 0000000..eb70b25 --- /dev/null +++ b/skills/immutability/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Lock collection permissions to make properties permanently immutable or permanently permitted +--- + + + +# Transferability & Update Rules + +Lock collection permissions to make properties permanently immutable or permanently permitted + +## When to use this skill + +Controls whether collection properties can be changed after creation. + +- Two states: FROZEN (permanentlyForbiddenTimes: FOREVER) or NEUTRAL (empty []) +- NEUTRAL [] = manager can update now AND can freeze it later. Use this for editable fields. +- FROZEN = permanent and irreversible. Use for fields that should never change. +- AVOID permanentlyPermittedTimes — it permanently prevents locking. Almost never needed. +- canUpdateCollectionApprovals: controls transfer rule mutability + - SECURITY: If manager can update Mint approvals, they can mint unlimited tokens + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "immutability"`. +- **CLI**: `bitbadges-cli sdk skills immutability` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/immutability + +## Category + +`advanced` + diff --git a/skills/liquidity-pools/SKILL.md b/skills/liquidity-pools/SKILL.md new file mode 100644 index 0000000..767895b --- /dev/null +++ b/skills/liquidity-pools/SKILL.md @@ -0,0 +1,31 @@ +--- +description: Liquidity pool standard with the 'Liquidity Pools' protocol standard tag — used for tradable assets that can be swapped on a DEX +--- + + + +# Liquidity Pools + +Liquidity pool standard with the "Liquidity Pools" protocol standard tag — used for tradable assets that can be swapped on a DEX + +## When to use this skill + +Required standards: ["Liquidity Pools"] + +- MUST set invariants.disablePoolCreation: false +- MUST configure at least one alias path (required for liquidity pools to function) +- Merkle challenges are NOT compatible with liquidity pools +- Enables decentralized exchange (DEX) trading interfaces + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "liquidity-pools"`. +- **CLI**: `bitbadges-cli sdk skills liquidity-pools` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/liquidity-pools + +## Category + +`token-type` + diff --git a/skills/minting/SKILL.md b/skills/minting/SKILL.md new file mode 100644 index 0000000..39bd6eb --- /dev/null +++ b/skills/minting/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Mint approval patterns including public mint, whitelist mint, creator-only mint, payment-gated mint, and escrow payouts +--- + + + +# Minting + +Mint approval patterns including public mint, whitelist mint, creator-only mint, payment-gated mint, and escrow payouts + +## When to use this skill + +Required fields for all minting approvals: +- fromListId: "Mint" +- overridesFromOutgoingApprovals: true (REQUIRED for ALL Mint approvals) +- autoApproveAllIncomingTransfers: true in defaultBalances (for public-mint collections) +- predeterminedBalances vs approvalAmounts: incompatible — use one or the other +- orderCalculationMethod: MUST have exactly ONE method set to true (default: useOverallNumTransfers) +- coinTransfers override flags: false for standard payments, true for escrow payouts +- Mint escrow: overrideFromWithApproverAddress: true + overrideToWithInitiator: true (pays the minter from the escrow address) + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "minting"`. +- **CLI**: `bitbadges-cli sdk skills minting` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/minting + +## Category + +`approval` + diff --git a/skills/multi-sig-voting/SKILL.md b/skills/multi-sig-voting/SKILL.md new file mode 100644 index 0000000..a96418b --- /dev/null +++ b/skills/multi-sig-voting/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Require weighted quorum voting from multiple parties before transfers can proceed (multi-sig, governance, etc.) +--- + + + +# Multi-Sig / Voting + +Require weighted quorum voting from multiple parties before transfers can proceed (multi-sig, governance, etc.) + +## When to use this skill + +Enables multi-signature-like approval via votingChallenges[] in approvalCriteria. + +- Each voter has an address and a weight +- quorumThreshold: percentage (0-100) of total possible weight that must vote "yes" +- Voters cast votes via MsgCastVote with yesWeight (0-100%) +- Non-voting voters count as 0% yes; threshold is % of ALL voters' total weight, not just those who voted +- Votes can be updated (re-casting overwrites previous vote) +- proposalId: unique identifier — changing it resets the vote tracker + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "multi-sig-voting"`. +- **CLI**: `bitbadges-cli sdk skills multi-sig-voting` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/multi-sig-voting + +## Category + +`approval` + diff --git a/skills/nft-collection/SKILL.md b/skills/nft-collection/SKILL.md new file mode 100644 index 0000000..84fbd63 --- /dev/null +++ b/skills/nft-collection/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Non-fungible token collection with unique token IDs, metadata URIs, and badge-based ownership +--- + + + +# NFT Collection + +Non-fungible token collection with unique token IDs, metadata URIs, and badge-based ownership + +## When to use this skill + +Required standards: ["NFTs"] +- For tradable NFTs: ["NFTs", "NFTMarketplace", "NFTPricingDenom:ubadge"] + +- validTokenIds: set to the range of unique token IDs (e.g. [{ "start": "1", "end": "100" }]) +- Each token ID represents a unique NFT; amount in transfers is typically "1" +- Use {id} placeholder in tokenMetadata URI for per-token metadata (e.g. "ipfs://QmHash/{id}") +- Mint approvals MUST have overridesFromOutgoingApprovals: true +- Ownership times are usually forever for NFTs + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "nft-collection"`. +- **CLI**: `bitbadges-cli sdk skills nft-collection` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/nft-collection + +## Category + +`token-type` + diff --git a/skills/payment-protocol/SKILL.md b/skills/payment-protocol/SKILL.md new file mode 100644 index 0000000..4f1ebed --- /dev/null +++ b/skills/payment-protocol/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Invoices, escrows, bounties, milestones, and multi-party agreements using coinTransfer-based approvals or IBC-backed smart token escrow +--- + + + +# Payment Protocol + +Invoices, escrows, bounties, milestones, and multi-party agreements using coinTransfer-based approvals or IBC-backed smart token escrow + +## When to use this skill + +Build invoices, milestones, bounties, escrow agreements, or any payment flow. + +Two approaches: +- **Approach 1 (coinTransfer-based)**: Simple one-shot payments. Each approval = one invoice/milestone with coinTransfers. + - Standards: ["ListView:Milestones"] or ["ListView:Invoice Requests"] or ["ListView:Bounties"] + - Each approval: fromListId "Mint", coinTransfers for payment, overridesFromOutgoingApprovals: true + - ListView incompatible with: Subscriptions, Smart Tokens, Custom 2FA, Liquidity Pools, Tradable NFTs +- **Approach 2 (Escrow)**: Funds held in IBC-backed smart token until conditions are met. + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "payment-protocol"`. +- **CLI**: `bitbadges-cli sdk skills payment-protocol` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/payment-protocol + +## Category + +`token-type` + diff --git a/skills/prediction-market/SKILL.md b/skills/prediction-market/SKILL.md new file mode 100644 index 0000000..b519d4e --- /dev/null +++ b/skills/prediction-market/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Binary prediction market with YES/NO outcome tokens, liquidity pool trading, and vote-based settlement +--- + + + +# Prediction Market + +Binary prediction market with YES/NO outcome tokens, liquidity pool trading, and vote-based settlement + +## When to use this skill + +Required standards: ["Prediction Market"] + +- Binary prediction market: "Will X happen by Y?" Users deposit USDC to mint paired YES+NO tokens. Trade YES↔NO on a liquidity pool. Verifier settles by voting. Winner redeems 1:1. +- Token ID 1 = YES, Token ID 2 = NO (via alias paths with 6 decimals) +- mintEscrowAddress holds all deposited USDC +- invariants: \`noForcefulPostMintTransfers: true\` — locks non-mint approvals (redeem, settlement, transferable) from using \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\`. Non-mint approvals rely on \`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\` for outgoing-side auth and on the burn destination for incoming-side auth +- All permissions frozen after creation +- 7 approvals: paired mint, freely transferable, pre-settlement redeem, yes-wins, no-wins, push-yes, push-no + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "prediction-market"`. +- **CLI**: `bitbadges-cli sdk skills prediction-market` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/prediction-market + +## Category + +`token-type` + diff --git a/skills/product-catalog/SKILL.md b/skills/product-catalog/SKILL.md new file mode 100644 index 0000000..1a1b28d --- /dev/null +++ b/skills/product-catalog/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Multi-product storefront with per-product pricing, supply limits, and optional burn-on-purchase. Each product is a separate token ID. +--- + + + +# Products + +Multi-product storefront with per-product pricing, supply limits, and optional burn-on-purchase. Each product is a separate token ID. + +## When to use this skill + +Required standards: ["Products"] + +- N token IDs (one per product), starting at 1 +- N+1 approvals: 1 purchase approval per product + 1 optional burn approval +- Each purchase approval: fromListId="Mint", toListId="All" (or burn address if burn-on-purchase), 1 coinTransfer paying the store address +- Payment goes directly to store address (NOT to escrow) — overrideFromWithApproverAddress: false +- Each product has independent price, supply limit (maxNumTransfers), and burn-on-purchase toggle +- predeterminedBalances.incrementedBalances.startBalances: 1x of that product's token ID + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "product-catalog"`. +- **CLI**: `bitbadges-cli sdk skills product-catalog` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/product-catalog + +## Category + +`token-type` + 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/quest/SKILL.md b/skills/quest/SKILL.md new file mode 100644 index 0000000..544e00a --- /dev/null +++ b/skills/quest/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Quest/reward collection — users complete criteria and claim a badge + coin payout +--- + + + +# Quest + +Quest/reward collection — users complete criteria and claim a badge + coin payout + +## When to use this skill + +Required standards: ["Quests"] + +- Single token only: validTokenIds = [{start: "1", end: "1"}] +- Quest approval MUST be properly gated — typically via an off-chain claim (merkle challenge with claimConfig), but can also use on-chain criteria (mustOwnTokens, dynamicStoreChallenges, evmQueryChallenges, votingChallenges) +- Coin transfers with overrideFromWithApproverAddress: true + overrideToWithInitiator: true +- predeterminedBalances: amount 1, no increments, no recurring, no duration +- Escrow funded upfront via set_mint_escrow_coins (rewardAmount * maxClaims) +- invariants.noCustomOwnershipTimes: true + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "quest"`. +- **CLI**: `bitbadges-cli sdk skills quest` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/quest + +## Category + +`token-type` + 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. diff --git a/skills/smart-token/SKILL.md b/skills/smart-token/SKILL.md new file mode 100644 index 0000000..8cc200e --- /dev/null +++ b/skills/smart-token/SKILL.md @@ -0,0 +1,33 @@ +--- +description: IBC-backed smart token with 1:1 backing and two required approvals (backing + unbacking) +--- + + + +# Smart Token + +IBC-backed smart token with 1:1 backing and two required approvals (backing + unbacking) + +## When to use this skill + +Required standards: ["Smart Token"] + +- MUST include cosmosCoinBackedPath in invariants with conversion sideA/sideB +- MUST configure at least one alias path (decimals must match IBC denom decimals) +- MUST create TWO required collection approvals (backing + unbacking). Transferable approval is COMMON but OPTIONAL: + 1. Backing approval (REQUIRED): fromListId = backing address, allowBackedMinting: true, mustPrioritize: true + 2. Transferable approval (OPTIONAL — include for wrapped assets, omit for vaults/escrows): fromListId = "!Mint", toListId = "All" + 3. Unbacking approval (REQUIRED): toListId = backing address, allowBackedMinting: true, mustPrioritize: true + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "smart-token"`. +- **CLI**: `bitbadges-cli sdk skills smart-token` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/smart-token + +## Category + +`token-type` + diff --git a/skills/subscription/SKILL.md b/skills/subscription/SKILL.md new file mode 100644 index 0000000..a94f807 --- /dev/null +++ b/skills/subscription/SKILL.md @@ -0,0 +1,33 @@ +--- +description: Time-based subscription token with recurring payment approvals and auto-deletion on expiry +--- + + + +# Subscription + +Time-based subscription token with recurring payment approvals and auto-deletion on expiry + +## When to use this skill + +Required standards: ["Subscriptions"] + +- validTokenIds: MUST be exactly one token ID [{ "start": "1", "end": "1" }] +- Subscription faucet approval requirements: + - fromListId: "Mint" + - overridesFromOutgoingApprovals: true + - coinTransfers: at least 1 entry, both override flags false + - predeterminedBalances.incrementedBalances.durationFromTimestamp: MUST be non-zero (duration in ms) + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "subscription"`. +- **CLI**: `bitbadges-cli sdk skills subscription` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/subscription + +## Category + +`token-type` + diff --git a/skills/tradable/SKILL.md b/skills/tradable/SKILL.md new file mode 100644 index 0000000..538ff13 --- /dev/null +++ b/skills/tradable/SKILL.md @@ -0,0 +1,33 @@ +--- +description: NFT marketplace standard enabling peer-to-peer transfers with the 'NFTMarketplace' standard tag and NFTPricingDenom +--- + + + +# Tradable NFTs + +NFT marketplace standard enabling peer-to-peer transfers with the "NFTMarketplace" standard tag and NFTPricingDenom + +## When to use this skill + +Required standards: ["NFTMarketplace", "NFTs", "NFTPricingDenom:ubadge"] + +- MUST include all three standards together +- NFTPricingDenom format: "NFTPricingDenom:" (sets pricing denomination for orderbook) +- MUST include a free transfer approval: fromListId: "!Mint", toListId: "All", initiatedByListId: "All", approvalId: "transferable-approval" +- Enables orderbook/marketplace integration +- Typically used with NFT collections +- Note: Legacy names "Tradable" and "DefaultDisplayCurrency" are still accepted for existing collections + +## Get the full instructions + +The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: + +- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "tradable"`. +- **CLI**: `bitbadges-cli sdk skills tradable` +- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/tradable + +## Category + +`standard` + From 88d37a97dfa84b077a7ba4b29c593a0248b06c86 Mon Sep 17 00:00:00 2001 From: Trevor Miller Date: Sun, 26 Apr 2026 08:39:46 -0400 Subject: [PATCH 2/4] Restructure skills into build/ and operations/; reframe install order MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two changes per maintainer feedback: 1. Skills directory hierarchy — operational skills (review, simulate, query, address, claim, broadcast, explain) move under skills/operations/. The 22 SDK-generated skills move under skills/build/. broadcast and credit-token shouldn't sit at the same level; this makes the conceptual split explicit. 2. README + setup.md reframe — the chain binary + CLI install (curl install.bitbadges.io | sh) is THE entrypoint. The plugin is a convenience layer on top, not a way to skip the CLI install. - README: new "Prerequisites" section with the install one-liner leads. The plugin install comes after. The npx fallback is documented as "graceful degradation, not the recommended path". - commands/setup.md: chain + CLI checks are required (not gated to broadcast use cases). Step ordering reflects the priority. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 44 ++++++++++++------- commands/setup.md | 24 +++++----- skills/{ => build}/address-list/SKILL.md | 0 skills/{ => build}/auction/SKILL.md | 0 skills/{ => build}/auto-mint/SKILL.md | 0 skills/{ => build}/bb-402/SKILL.md | 0 skills/{ => build}/bounty/SKILL.md | 0 skills/{ => build}/burnable/SKILL.md | 0 skills/{ => build}/credit-token/SKILL.md | 0 skills/{ => build}/crowdfund/SKILL.md | 0 skills/{ => build}/custom-2fa/SKILL.md | 0 skills/{ => build}/fungible-token/SKILL.md | 0 skills/{ => build}/immutability/SKILL.md | 0 skills/{ => build}/liquidity-pools/SKILL.md | 0 skills/{ => build}/minting/SKILL.md | 0 skills/{ => build}/multi-sig-voting/SKILL.md | 0 skills/{ => build}/nft-collection/SKILL.md | 0 skills/{ => build}/payment-protocol/SKILL.md | 0 skills/{ => build}/prediction-market/SKILL.md | 0 skills/{ => build}/product-catalog/SKILL.md | 0 skills/{ => build}/quest/SKILL.md | 0 skills/{ => build}/smart-token/SKILL.md | 0 skills/{ => build}/subscription/SKILL.md | 0 skills/{ => build}/tradable/SKILL.md | 0 skills/{ => operations}/address/SKILL.md | 0 skills/{ => operations}/broadcast/SKILL.md | 0 skills/{ => operations}/claim/SKILL.md | 0 skills/{ => operations}/explain/SKILL.md | 0 skills/{ => operations}/query/SKILL.md | 0 skills/{ => operations}/review/SKILL.md | 0 skills/{ => operations}/simulate/SKILL.md | 0 31 files changed, 39 insertions(+), 29 deletions(-) rename skills/{ => build}/address-list/SKILL.md (100%) rename skills/{ => build}/auction/SKILL.md (100%) rename skills/{ => build}/auto-mint/SKILL.md (100%) rename skills/{ => build}/bb-402/SKILL.md (100%) rename skills/{ => build}/bounty/SKILL.md (100%) rename skills/{ => build}/burnable/SKILL.md (100%) rename skills/{ => build}/credit-token/SKILL.md (100%) rename skills/{ => build}/crowdfund/SKILL.md (100%) rename skills/{ => build}/custom-2fa/SKILL.md (100%) rename skills/{ => build}/fungible-token/SKILL.md (100%) rename skills/{ => build}/immutability/SKILL.md (100%) rename skills/{ => build}/liquidity-pools/SKILL.md (100%) rename skills/{ => build}/minting/SKILL.md (100%) rename skills/{ => build}/multi-sig-voting/SKILL.md (100%) rename skills/{ => build}/nft-collection/SKILL.md (100%) rename skills/{ => build}/payment-protocol/SKILL.md (100%) rename skills/{ => build}/prediction-market/SKILL.md (100%) rename skills/{ => build}/product-catalog/SKILL.md (100%) rename skills/{ => build}/quest/SKILL.md (100%) rename skills/{ => build}/smart-token/SKILL.md (100%) rename skills/{ => build}/subscription/SKILL.md (100%) rename skills/{ => build}/tradable/SKILL.md (100%) rename skills/{ => operations}/address/SKILL.md (100%) rename skills/{ => operations}/broadcast/SKILL.md (100%) rename skills/{ => operations}/claim/SKILL.md (100%) rename skills/{ => operations}/explain/SKILL.md (100%) rename skills/{ => operations}/query/SKILL.md (100%) rename skills/{ => operations}/review/SKILL.md (100%) rename skills/{ => operations}/simulate/SKILL.md (100%) diff --git a/README.md b/README.md index 4f2b823..d79eb81 100644 --- a/README.md +++ b/README.md @@ -2,34 +2,44 @@ 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. -## Install +## Prerequisites -``` -/plugin marketplace add BitBadges/bitbadges-plugin -/plugin install bitbadges -``` - -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). +- **~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`. +- **`bitbadges-builder` subagent** for focused builder loops. +- **SessionStart pre-warm** so the first MCP-tool call doesn't pay npx download latency. + +## 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/commands/setup.md b/commands/setup.md index 2d6d09b..0f6d583 100644 --- a/commands/setup.md +++ b/commands/setup.md @@ -5,22 +5,22 @@ argument-hint: (no arguments) # /bitbadges:setup -Run this once after installing the plugin. It does four things: +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. -1. **Checks the chain binary.** If `bitbadgeschaind` is on PATH, prints the version. If not, prints the install one-liner (`curl -fsSL https://install.bitbadges.io | sh`) and asks for explicit consent before running it. -2. **Checks the JS CLI.** If `bitbadges-cli` is reachable (or `npx bitbadges --version` works), reports OK. If not, suggests the same one-liner. -3. **Reads existing API key.** If `~/.bitbadges/config.json` already has an `apiKey`, uses that — no prompt. The CLI config is canonical; the plugin reads from it. -4. **Otherwise prompts for API key** and writes it via `bitbadges-cli config set apiKey ` so both the CLI and the plugin pick it up. Sources: get an API key at https://bitbadges.io/developer. +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. -5. **Migration check.** 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. +## What it does -## Behavior summary for Claude +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. -When the user runs `/bitbadges:setup`: +## Behavior summary for Claude -- Run `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh --json` to enumerate the current state. -- Walk the four checks above in order. -- For each missing prerequisite, **show** the command but do not run it without an explicit "yes" from the user. Never auto-pipe `curl ... | sh`. +- 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 (`bitbadges-cli config set apiKey `) so it works for everything: CLI, MCP, plugin, manual scripts. +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/skills/address-list/SKILL.md b/skills/build/address-list/SKILL.md similarity index 100% rename from skills/address-list/SKILL.md rename to skills/build/address-list/SKILL.md diff --git a/skills/auction/SKILL.md b/skills/build/auction/SKILL.md similarity index 100% rename from skills/auction/SKILL.md rename to skills/build/auction/SKILL.md diff --git a/skills/auto-mint/SKILL.md b/skills/build/auto-mint/SKILL.md similarity index 100% rename from skills/auto-mint/SKILL.md rename to skills/build/auto-mint/SKILL.md diff --git a/skills/bb-402/SKILL.md b/skills/build/bb-402/SKILL.md similarity index 100% rename from skills/bb-402/SKILL.md rename to skills/build/bb-402/SKILL.md diff --git a/skills/bounty/SKILL.md b/skills/build/bounty/SKILL.md similarity index 100% rename from skills/bounty/SKILL.md rename to skills/build/bounty/SKILL.md diff --git a/skills/burnable/SKILL.md b/skills/build/burnable/SKILL.md similarity index 100% rename from skills/burnable/SKILL.md rename to skills/build/burnable/SKILL.md diff --git a/skills/credit-token/SKILL.md b/skills/build/credit-token/SKILL.md similarity index 100% rename from skills/credit-token/SKILL.md rename to skills/build/credit-token/SKILL.md diff --git a/skills/crowdfund/SKILL.md b/skills/build/crowdfund/SKILL.md similarity index 100% rename from skills/crowdfund/SKILL.md rename to skills/build/crowdfund/SKILL.md diff --git a/skills/custom-2fa/SKILL.md b/skills/build/custom-2fa/SKILL.md similarity index 100% rename from skills/custom-2fa/SKILL.md rename to skills/build/custom-2fa/SKILL.md diff --git a/skills/fungible-token/SKILL.md b/skills/build/fungible-token/SKILL.md similarity index 100% rename from skills/fungible-token/SKILL.md rename to skills/build/fungible-token/SKILL.md diff --git a/skills/immutability/SKILL.md b/skills/build/immutability/SKILL.md similarity index 100% rename from skills/immutability/SKILL.md rename to skills/build/immutability/SKILL.md diff --git a/skills/liquidity-pools/SKILL.md b/skills/build/liquidity-pools/SKILL.md similarity index 100% rename from skills/liquidity-pools/SKILL.md rename to skills/build/liquidity-pools/SKILL.md diff --git a/skills/minting/SKILL.md b/skills/build/minting/SKILL.md similarity index 100% rename from skills/minting/SKILL.md rename to skills/build/minting/SKILL.md diff --git a/skills/multi-sig-voting/SKILL.md b/skills/build/multi-sig-voting/SKILL.md similarity index 100% rename from skills/multi-sig-voting/SKILL.md rename to skills/build/multi-sig-voting/SKILL.md diff --git a/skills/nft-collection/SKILL.md b/skills/build/nft-collection/SKILL.md similarity index 100% rename from skills/nft-collection/SKILL.md rename to skills/build/nft-collection/SKILL.md diff --git a/skills/payment-protocol/SKILL.md b/skills/build/payment-protocol/SKILL.md similarity index 100% rename from skills/payment-protocol/SKILL.md rename to skills/build/payment-protocol/SKILL.md diff --git a/skills/prediction-market/SKILL.md b/skills/build/prediction-market/SKILL.md similarity index 100% rename from skills/prediction-market/SKILL.md rename to skills/build/prediction-market/SKILL.md diff --git a/skills/product-catalog/SKILL.md b/skills/build/product-catalog/SKILL.md similarity index 100% rename from skills/product-catalog/SKILL.md rename to skills/build/product-catalog/SKILL.md diff --git a/skills/quest/SKILL.md b/skills/build/quest/SKILL.md similarity index 100% rename from skills/quest/SKILL.md rename to skills/build/quest/SKILL.md diff --git a/skills/smart-token/SKILL.md b/skills/build/smart-token/SKILL.md similarity index 100% rename from skills/smart-token/SKILL.md rename to skills/build/smart-token/SKILL.md diff --git a/skills/subscription/SKILL.md b/skills/build/subscription/SKILL.md similarity index 100% rename from skills/subscription/SKILL.md rename to skills/build/subscription/SKILL.md diff --git a/skills/tradable/SKILL.md b/skills/build/tradable/SKILL.md similarity index 100% rename from skills/tradable/SKILL.md rename to skills/build/tradable/SKILL.md diff --git a/skills/address/SKILL.md b/skills/operations/address/SKILL.md similarity index 100% rename from skills/address/SKILL.md rename to skills/operations/address/SKILL.md diff --git a/skills/broadcast/SKILL.md b/skills/operations/broadcast/SKILL.md similarity index 100% rename from skills/broadcast/SKILL.md rename to skills/operations/broadcast/SKILL.md diff --git a/skills/claim/SKILL.md b/skills/operations/claim/SKILL.md similarity index 100% rename from skills/claim/SKILL.md rename to skills/operations/claim/SKILL.md diff --git a/skills/explain/SKILL.md b/skills/operations/explain/SKILL.md similarity index 100% rename from skills/explain/SKILL.md rename to skills/operations/explain/SKILL.md diff --git a/skills/query/SKILL.md b/skills/operations/query/SKILL.md similarity index 100% rename from skills/query/SKILL.md rename to skills/operations/query/SKILL.md diff --git a/skills/review/SKILL.md b/skills/operations/review/SKILL.md similarity index 100% rename from skills/review/SKILL.md rename to skills/operations/review/SKILL.md diff --git a/skills/simulate/SKILL.md b/skills/operations/simulate/SKILL.md similarity index 100% rename from skills/simulate/SKILL.md rename to skills/operations/simulate/SKILL.md From 413848ecc5cacf587162c30a58518a83e75c2f27 Mon Sep 17 00:00:00 2001 From: Trevor Miller Date: Sun, 26 Apr 2026 12:40:19 -0400 Subject: [PATCH 3/4] Revamp: harness on top of the CLI, not a duplicate skill catalog The 22 generated SKILL.md files in skills/build// duplicated content already available via `bitbadges-cli sdk skills `, the get_skill_instructions MCP tool, and the Gitbook pages at docs.bitbadges.io/x-tokenization/examples/skills/. Three places to keep in sync, no real value added by the plugin since each was just a routing wrapper anyway. New shape: one `build` skill that's a meta-guide. Teaches Claude to: 1. Discover token types via `bitbadges-cli sdk skills` 2. Load canonical instructions via MCP `get_skill_instructions(id)` or `bitbadges-cli sdk skills ` or the Gitbook pages 3. Construct via per-field MCP session tools 4. Validate / review / simulate before routing to broadcast Plus the existing 7 operational skills (review, simulate, explain, query, address, claim, broadcast), now flattened up from skills/operations/* to skills/* since the build/operations distinction is moot with only one build skill. = 8 skills total, flat. Each is a guide on how to leverage the CLI + MCP + docs for one workflow, not a redefinition of what BitBadges provides. Source of truth stays in the SDK. README + CHANGELOG updated to reflect the new philosophy. The plugin is "a thin harness, not a knowledge base". Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 11 +++- README.md | 16 ++++-- skills/{operations => }/address/SKILL.md | 0 skills/{operations => }/broadcast/SKILL.md | 0 skills/build/SKILL.md | 64 ++++++++++++++++++++++ skills/build/address-list/SKILL.md | 33 ----------- skills/build/auction/SKILL.md | 33 ----------- skills/build/auto-mint/SKILL.md | 33 ----------- skills/build/bb-402/SKILL.md | 33 ----------- skills/build/bounty/SKILL.md | 33 ----------- skills/build/burnable/SKILL.md | 33 ----------- skills/build/credit-token/SKILL.md | 36 ------------ skills/build/crowdfund/SKILL.md | 33 ----------- skills/build/custom-2fa/SKILL.md | 32 ----------- skills/build/fungible-token/SKILL.md | 32 ----------- skills/build/immutability/SKILL.md | 33 ----------- skills/build/liquidity-pools/SKILL.md | 31 ----------- skills/build/minting/SKILL.md | 33 ----------- skills/build/multi-sig-voting/SKILL.md | 33 ----------- skills/build/nft-collection/SKILL.md | 33 ----------- skills/build/payment-protocol/SKILL.md | 33 ----------- skills/build/prediction-market/SKILL.md | 33 ----------- skills/build/product-catalog/SKILL.md | 33 ----------- skills/build/quest/SKILL.md | 33 ----------- skills/build/smart-token/SKILL.md | 33 ----------- skills/build/subscription/SKILL.md | 33 ----------- skills/build/tradable/SKILL.md | 33 ----------- skills/{operations => }/claim/SKILL.md | 0 skills/{operations => }/explain/SKILL.md | 0 skills/{operations => }/query/SKILL.md | 0 skills/{operations => }/review/SKILL.md | 0 skills/{operations => }/simulate/SKILL.md | 0 32 files changed, 85 insertions(+), 731 deletions(-) rename skills/{operations => }/address/SKILL.md (100%) rename skills/{operations => }/broadcast/SKILL.md (100%) create mode 100644 skills/build/SKILL.md delete mode 100644 skills/build/address-list/SKILL.md delete mode 100644 skills/build/auction/SKILL.md delete mode 100644 skills/build/auto-mint/SKILL.md delete mode 100644 skills/build/bb-402/SKILL.md delete mode 100644 skills/build/bounty/SKILL.md delete mode 100644 skills/build/burnable/SKILL.md delete mode 100644 skills/build/credit-token/SKILL.md delete mode 100644 skills/build/crowdfund/SKILL.md delete mode 100644 skills/build/custom-2fa/SKILL.md delete mode 100644 skills/build/fungible-token/SKILL.md delete mode 100644 skills/build/immutability/SKILL.md delete mode 100644 skills/build/liquidity-pools/SKILL.md delete mode 100644 skills/build/minting/SKILL.md delete mode 100644 skills/build/multi-sig-voting/SKILL.md delete mode 100644 skills/build/nft-collection/SKILL.md delete mode 100644 skills/build/payment-protocol/SKILL.md delete mode 100644 skills/build/prediction-market/SKILL.md delete mode 100644 skills/build/product-catalog/SKILL.md delete mode 100644 skills/build/quest/SKILL.md delete mode 100644 skills/build/smart-token/SKILL.md delete mode 100644 skills/build/subscription/SKILL.md delete mode 100644 skills/build/tradable/SKILL.md rename skills/{operations => }/claim/SKILL.md (100%) rename skills/{operations => }/explain/SKILL.md (100%) rename skills/{operations => }/query/SKILL.md (100%) rename skills/{operations => }/review/SKILL.md (100%) rename skills/{operations => }/simulate/SKILL.md (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 72e5a75..5596d33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,9 +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. -- 22 generated SKILL.md files (one per SDK `SKILL_INSTRUCTIONS` id), produced by the SDK's `gen-llm-mirrors` generator. Source of truth stays in `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts`. -- 7 hand-written operational skills: `review`, `simulate`, `explain`, `query`, `address`, `claim`, `broadcast`. +- 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 d79eb81..9ba42fa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # 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. + +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. ## Prerequisites @@ -31,12 +33,18 @@ Then run `/bitbadges:setup` once to verify everything is wired and `/bitbadges:s ## What the plugin adds -- **MCP tools** — `bitbadges-builder` registered automatically (no separate `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`. +- **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. diff --git a/skills/operations/address/SKILL.md b/skills/address/SKILL.md similarity index 100% rename from skills/operations/address/SKILL.md rename to skills/address/SKILL.md diff --git a/skills/operations/broadcast/SKILL.md b/skills/broadcast/SKILL.md similarity index 100% rename from skills/operations/broadcast/SKILL.md rename to skills/broadcast/SKILL.md 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/build/address-list/SKILL.md b/skills/build/address-list/SKILL.md deleted file mode 100644 index 25b186f..0000000 --- a/skills/build/address-list/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: On-chain address list where membership = owning x1 of token ID 1. Manager can add/remove addresses. ---- - - - -# Address List - -On-chain address list where membership = owning x1 of token ID 1. Manager can add/remove addresses. - -## When to use this skill - -Required standards: ["Address List"] - -- validTokenIds: MUST be exactly [{ "start": "1", "end": "1" }] -- TWO collection approvals required with EXACT approvalIds (frontend depends on these): - 1. "manager-add": fromListId "Mint", toListId "All", initiatedByListId = creator. Mints token to add address. - 2. "manager-remove": fromListId "All", toListId burn address (bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqs7gvmv), initiatedByListId = creator. Burns token to remove address. -- BOTH approvals MUST have overridesFromOutgoingApprovals: true -- NO peer-to-peer transfer approval — only manager can modify the list - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "address-list"`. -- **CLI**: `bitbadges-cli sdk skills address-list` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/address-list - -## Category - -`token-type` - diff --git a/skills/build/auction/SKILL.md b/skills/build/auction/SKILL.md deleted file mode 100644 index 1544597..0000000 --- a/skills/build/auction/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Single-item auction with intent-based bidding. Seller mints NFT directly to the winning bidder during the accept window. ---- - - - -# Auction - -Single-item auction with intent-based bidding. Seller mints NFT directly to the winning bidder during the accept window. - -## When to use this skill - -Required standards: ["Auction"] - -- 1 token ID (the auctioned item) -- 2 collection-level approvals: mint-to-winner (combines mint + accept), burn (cleanup) -- Mint-to-winner: seller mints NFT directly to winning bidder during accept window (bidDeadline → bidDeadline + acceptWindow) -- No separate mint-at-creation step — token doesn't exist until seller accepts a bid -- Burn: anyone can burn token to burn address (permanent cleanup) -- Bidding via user-level outgoing approval intents (not collection approvals) - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "auction"`. -- **CLI**: `bitbadges-cli sdk skills auction` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/auction - -## Category - -`token-type` - diff --git a/skills/build/auto-mint/SKILL.md b/skills/build/auto-mint/SKILL.md deleted file mode 100644 index 583b0a5..0000000 --- a/skills/build/auto-mint/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Mint and distribute tokens to recipients at collection creation time using MsgTransferTokens ---- - - - -# Auto-Mint - -Mint and distribute tokens to recipients at collection creation time using MsgTransferTokens - -## When to use this skill - -Post-creation minting — adds MsgTransferTokens messages to the transaction so tokens are distributed immediately after collection creation. - -- Transaction can contain MsgUniversalUpdateCollection PLUS one or more MsgTransferTokens messages -- All transfer messages use collectionId: "0" to reference the just-created collection -- prioritizedApprovals MUST always be specified (use [] if none needed) -- from: "Mint" for minting new tokens, bb1... address for peer-to-peer transfers -- The signing user (creator) is the initiator — collection must have an approval allowing this -- All numbers as strings — "1" not 1 - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "auto-mint"`. -- **CLI**: `bitbadges-cli sdk skills auto-mint` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/auto-mint - -## Category - -`feature` - diff --git a/skills/build/bb-402/SKILL.md b/skills/build/bb-402/SKILL.md deleted file mode 100644 index 5c39846..0000000 --- a/skills/build/bb-402/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Token-gated access protocol where ownership of specific badges grants API/resource access ---- - - - -# BB-402 Token-Gated Access - -Token-gated access protocol where ownership of specific badges grants API/resource access - -## When to use this skill - -Protocol for token-gated access to APIs/resources using HTTP 402 Payment Required. - -- Flow: client requests resource -> server returns 402 + required badge criteria -> client proves ownership -> server validates via BitBadges API -- ownershipRequirements: use $and for "must have all", $or for "must have any" -- mustOwnAmounts: { start: 1, end: 1 } = must own at least 1 -- mustOwnAmounts: { start: 0, end: 0 } = must NOT own (exclusion) -- Tiered access: different token IDs = different access levels -- Time-bounded access: combine ownershipTimes with subscription tokens - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "bb-402"`. -- **CLI**: `bitbadges-cli sdk skills bb-402` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/bb-402 - -## Category - -`feature` - diff --git a/skills/build/bounty/SKILL.md b/skills/build/bounty/SKILL.md deleted file mode 100644 index 8cc2ebe..0000000 --- a/skills/build/bounty/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Escrow-based bounty with verifier arbitration. Submitter escrows coins, verifier accepts (pays recipient) or denies (refunds submitter). Expires if no decision. ---- - - - -# Bounty - -Escrow-based bounty with verifier arbitration. Submitter escrows coins, verifier accepts (pays recipient) or denies (refunds submitter). Expires if no decision. - -## When to use this skill - -Required standards: ["Bounty"] - -- 1 token ID (vehicle for approval engine — minted directly to burn) -- 3 collection-level approvals: accept, deny, expire -- Each approval: Mint → burn 1x token ID 1, triggers coinTransfer as side effect -- Verifier decides outcome via MsgCastVote -- Escrow pre-funded at creation via mintEscrowCoinsToTransfer -- Fixed bounty amount, no amount scaling - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "bounty"`. -- **CLI**: `bitbadges-cli sdk skills bounty` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/bounty - -## Category - -`token-type` - diff --git a/skills/build/burnable/SKILL.md b/skills/build/burnable/SKILL.md deleted file mode 100644 index 3b9b9e8..0000000 --- a/skills/build/burnable/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Allow token holders to burn tokens by sending them to the burn address, permanently removing them from circulation ---- - - - -# Burnable - -Allow token holders to burn tokens by sending them to the burn address, permanently removing them from circulation - -## When to use this skill - -Allows holders to permanently destroy tokens by sending to burn address. - -- Burn address: bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqs7gvmv (ETH null address in BitBadges format) -- Approval structure: fromListId: "!Mint", toListId: burn address -- overridesToIncomingApprovals: true (burn address has no user-level incoming approvals) -- approvalId: "burnable-approval" (standard ID used by frontend to detect burnability) -- All amounts/transfers set to "0" (unlimited) -- Additive: sits alongside other collection approvals - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "burnable"`. -- **CLI**: `bitbadges-cli sdk skills burnable` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/burnable - -## Category - -`approval` - diff --git a/skills/build/credit-token/SKILL.md b/skills/build/credit-token/SKILL.md deleted file mode 100644 index 5910214..0000000 --- a/skills/build/credit-token/SKILL.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: Increment-only, non-transferable credit token purchased with any ICS20 denom. Users pay X of a denom and receive Y tokens as credits/proof of payment. For a 1:1 backed token with on-chain transferability, use the Smart Token standard inste… ---- - - - -# Credit Token - -Increment-only, non-transferable credit token purchased with any ICS20 denom. Users pay X of a denom and receive Y tokens as credits/proof of payment. For a 1:1 backed token with on-chain transferability, use the Smart Token standard instead. - -## When to use this skill - -Required standards: ["Credit Token"] - -- Increment-only, non-transferable (soulbound) fungible token purchased with ICS20 denom -- validTokenIds: [{ "start": "1", "end": "1" }] (single token ID) -- ONE Mint approval with approvalId "credit-scaled" using allowAmountScaling (single scaled approval supersedes the legacy 8-10 tier approach; legacy tiers still supported for backward compat but deprecated) -- Lock canUpdateCollectionApprovals (empty array = frozen) -- defaultBalances: autoApproveAllIncomingTransfers: true, autoApproveSelfInitiatedOutgoingTransfers: true, autoApproveSelfInitiatedIncomingTransfers: true -- Credit-scaled approval: overridesFromOutgoingApprovals: true, mustPrioritize: true, coinTransfers[0].coins[0].amount = "1" (micro-payment unit) - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "credit-token"`. -- **CLI**: `bitbadges-cli sdk skills credit-token` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/credit-token - -## Category - -`token-type` - -## Reference collections - -- [Collection 23](https://bitbadges.io/collections/23) diff --git a/skills/build/crowdfund/SKILL.md b/skills/build/crowdfund/SKILL.md deleted file mode 100644 index 925564f..0000000 --- a/skills/build/crowdfund/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: On-chain crowdfunding with goal tracking via mustOwnTokens. Contributors deposit funds, receive refund tokens. Crowdfunder withdraws if goal met, contributors refund if not. ---- - - - -# Crowdfund - -On-chain crowdfunding with goal tracking via mustOwnTokens. Contributors deposit funds, receive refund tokens. Crowdfunder withdraws if goal met, contributors refund if not. - -## When to use this skill - -Required standards: ["Crowdfund"] - -- 2 token IDs: Token 1 = Refund token (contributor holds), Token 2 = Progress token (crowdfunder accumulates) -- 4 collection-level approvals: deposit-refund, deposit-progress, success (withdraw), refund -- Contributors deposit coins → receive Token 1 (refund token). Paired approval mints Token 2 to crowdfunder (progress tracking). -- Success: crowdfunder withdraws if mustOwnTokens confirms they hold >= goal of Token 2 (collectionId: 0 = self-reference) -- Refund: after deadline, contributors burn Token 1 → escrow pays them back (only if goal NOT met via mustOwnTokens check) -- allowAmountScaling: true on ALL 4 approvals (contributors choose deposit size, everything scales proportionally) - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "crowdfund"`. -- **CLI**: `bitbadges-cli sdk skills crowdfund` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/crowdfund - -## Category - -`token-type` - diff --git a/skills/build/custom-2fa/SKILL.md b/skills/build/custom-2fa/SKILL.md deleted file mode 100644 index 14daac5..0000000 --- a/skills/build/custom-2fa/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: Two-factor authentication for transfers using a secondary approval address ---- - - - -# Custom 2FA - -Two-factor authentication for transfers using a secondary approval address - -## When to use this skill - -Required standards: ["Custom-2FA"] - -- autoDeletionOptions.allowPurgeIfExpired: MUST be true -- Approval name MUST contain "Custom 2FA" -- Use time-dependent ownershipTimes in MsgTransferTokens (not forever) -- Calculate timestamps: current time + expiration duration (milliseconds since epoch) -- Tokens automatically expire and can be purged after expiration - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "custom-2fa"`. -- **CLI**: `bitbadges-cli sdk skills custom-2fa` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/custom-2fa - -## Category - -`token-type` - diff --git a/skills/build/fungible-token/SKILL.md b/skills/build/fungible-token/SKILL.md deleted file mode 100644 index 16df1d4..0000000 --- a/skills/build/fungible-token/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: Simple fungible token with fixed or unlimited supply and configurable mint/transfer approvals ---- - - - -# Fungible Token - -Simple fungible token with fixed or unlimited supply and configurable mint/transfer approvals - -## When to use this skill - -Required standards: ["Fungible Tokens"] - -- validTokenIds: MUST be exactly [{ "start": "1", "end": "1" }] (single token ID) -- All tokens share the same token ID (1), making them interchangeable -- Amount field in transfers determines quantity -- Token metadata must reference token ID 1 -- Ownership times typically forever: [{ "start": "1", "end": "18446744073709551615" }] - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "fungible-token"`. -- **CLI**: `bitbadges-cli sdk skills fungible-token` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/fungible-token - -## Category - -`token-type` - diff --git a/skills/build/immutability/SKILL.md b/skills/build/immutability/SKILL.md deleted file mode 100644 index eb70b25..0000000 --- a/skills/build/immutability/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Lock collection permissions to make properties permanently immutable or permanently permitted ---- - - - -# Transferability & Update Rules - -Lock collection permissions to make properties permanently immutable or permanently permitted - -## When to use this skill - -Controls whether collection properties can be changed after creation. - -- Two states: FROZEN (permanentlyForbiddenTimes: FOREVER) or NEUTRAL (empty []) -- NEUTRAL [] = manager can update now AND can freeze it later. Use this for editable fields. -- FROZEN = permanent and irreversible. Use for fields that should never change. -- AVOID permanentlyPermittedTimes — it permanently prevents locking. Almost never needed. -- canUpdateCollectionApprovals: controls transfer rule mutability - - SECURITY: If manager can update Mint approvals, they can mint unlimited tokens - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "immutability"`. -- **CLI**: `bitbadges-cli sdk skills immutability` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/immutability - -## Category - -`advanced` - diff --git a/skills/build/liquidity-pools/SKILL.md b/skills/build/liquidity-pools/SKILL.md deleted file mode 100644 index 767895b..0000000 --- a/skills/build/liquidity-pools/SKILL.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: Liquidity pool standard with the 'Liquidity Pools' protocol standard tag — used for tradable assets that can be swapped on a DEX ---- - - - -# Liquidity Pools - -Liquidity pool standard with the "Liquidity Pools" protocol standard tag — used for tradable assets that can be swapped on a DEX - -## When to use this skill - -Required standards: ["Liquidity Pools"] - -- MUST set invariants.disablePoolCreation: false -- MUST configure at least one alias path (required for liquidity pools to function) -- Merkle challenges are NOT compatible with liquidity pools -- Enables decentralized exchange (DEX) trading interfaces - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "liquidity-pools"`. -- **CLI**: `bitbadges-cli sdk skills liquidity-pools` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/liquidity-pools - -## Category - -`token-type` - diff --git a/skills/build/minting/SKILL.md b/skills/build/minting/SKILL.md deleted file mode 100644 index 39bd6eb..0000000 --- a/skills/build/minting/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Mint approval patterns including public mint, whitelist mint, creator-only mint, payment-gated mint, and escrow payouts ---- - - - -# Minting - -Mint approval patterns including public mint, whitelist mint, creator-only mint, payment-gated mint, and escrow payouts - -## When to use this skill - -Required fields for all minting approvals: -- fromListId: "Mint" -- overridesFromOutgoingApprovals: true (REQUIRED for ALL Mint approvals) -- autoApproveAllIncomingTransfers: true in defaultBalances (for public-mint collections) -- predeterminedBalances vs approvalAmounts: incompatible — use one or the other -- orderCalculationMethod: MUST have exactly ONE method set to true (default: useOverallNumTransfers) -- coinTransfers override flags: false for standard payments, true for escrow payouts -- Mint escrow: overrideFromWithApproverAddress: true + overrideToWithInitiator: true (pays the minter from the escrow address) - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "minting"`. -- **CLI**: `bitbadges-cli sdk skills minting` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/minting - -## Category - -`approval` - diff --git a/skills/build/multi-sig-voting/SKILL.md b/skills/build/multi-sig-voting/SKILL.md deleted file mode 100644 index a96418b..0000000 --- a/skills/build/multi-sig-voting/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Require weighted quorum voting from multiple parties before transfers can proceed (multi-sig, governance, etc.) ---- - - - -# Multi-Sig / Voting - -Require weighted quorum voting from multiple parties before transfers can proceed (multi-sig, governance, etc.) - -## When to use this skill - -Enables multi-signature-like approval via votingChallenges[] in approvalCriteria. - -- Each voter has an address and a weight -- quorumThreshold: percentage (0-100) of total possible weight that must vote "yes" -- Voters cast votes via MsgCastVote with yesWeight (0-100%) -- Non-voting voters count as 0% yes; threshold is % of ALL voters' total weight, not just those who voted -- Votes can be updated (re-casting overwrites previous vote) -- proposalId: unique identifier — changing it resets the vote tracker - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "multi-sig-voting"`. -- **CLI**: `bitbadges-cli sdk skills multi-sig-voting` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/multi-sig-voting - -## Category - -`approval` - diff --git a/skills/build/nft-collection/SKILL.md b/skills/build/nft-collection/SKILL.md deleted file mode 100644 index 84fbd63..0000000 --- a/skills/build/nft-collection/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Non-fungible token collection with unique token IDs, metadata URIs, and badge-based ownership ---- - - - -# NFT Collection - -Non-fungible token collection with unique token IDs, metadata URIs, and badge-based ownership - -## When to use this skill - -Required standards: ["NFTs"] -- For tradable NFTs: ["NFTs", "NFTMarketplace", "NFTPricingDenom:ubadge"] - -- validTokenIds: set to the range of unique token IDs (e.g. [{ "start": "1", "end": "100" }]) -- Each token ID represents a unique NFT; amount in transfers is typically "1" -- Use {id} placeholder in tokenMetadata URI for per-token metadata (e.g. "ipfs://QmHash/{id}") -- Mint approvals MUST have overridesFromOutgoingApprovals: true -- Ownership times are usually forever for NFTs - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "nft-collection"`. -- **CLI**: `bitbadges-cli sdk skills nft-collection` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/nft-collection - -## Category - -`token-type` - diff --git a/skills/build/payment-protocol/SKILL.md b/skills/build/payment-protocol/SKILL.md deleted file mode 100644 index 4f1ebed..0000000 --- a/skills/build/payment-protocol/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Invoices, escrows, bounties, milestones, and multi-party agreements using coinTransfer-based approvals or IBC-backed smart token escrow ---- - - - -# Payment Protocol - -Invoices, escrows, bounties, milestones, and multi-party agreements using coinTransfer-based approvals or IBC-backed smart token escrow - -## When to use this skill - -Build invoices, milestones, bounties, escrow agreements, or any payment flow. - -Two approaches: -- **Approach 1 (coinTransfer-based)**: Simple one-shot payments. Each approval = one invoice/milestone with coinTransfers. - - Standards: ["ListView:Milestones"] or ["ListView:Invoice Requests"] or ["ListView:Bounties"] - - Each approval: fromListId "Mint", coinTransfers for payment, overridesFromOutgoingApprovals: true - - ListView incompatible with: Subscriptions, Smart Tokens, Custom 2FA, Liquidity Pools, Tradable NFTs -- **Approach 2 (Escrow)**: Funds held in IBC-backed smart token until conditions are met. - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "payment-protocol"`. -- **CLI**: `bitbadges-cli sdk skills payment-protocol` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/payment-protocol - -## Category - -`token-type` - diff --git a/skills/build/prediction-market/SKILL.md b/skills/build/prediction-market/SKILL.md deleted file mode 100644 index b519d4e..0000000 --- a/skills/build/prediction-market/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Binary prediction market with YES/NO outcome tokens, liquidity pool trading, and vote-based settlement ---- - - - -# Prediction Market - -Binary prediction market with YES/NO outcome tokens, liquidity pool trading, and vote-based settlement - -## When to use this skill - -Required standards: ["Prediction Market"] - -- Binary prediction market: "Will X happen by Y?" Users deposit USDC to mint paired YES+NO tokens. Trade YES↔NO on a liquidity pool. Verifier settles by voting. Winner redeems 1:1. -- Token ID 1 = YES, Token ID 2 = NO (via alias paths with 6 decimals) -- mintEscrowAddress holds all deposited USDC -- invariants: \`noForcefulPostMintTransfers: true\` — locks non-mint approvals (redeem, settlement, transferable) from using \`overridesFromOutgoingApprovals\` or \`overridesToIncomingApprovals\`. Non-mint approvals rely on \`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\` for outgoing-side auth and on the burn destination for incoming-side auth -- All permissions frozen after creation -- 7 approvals: paired mint, freely transferable, pre-settlement redeem, yes-wins, no-wins, push-yes, push-no - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "prediction-market"`. -- **CLI**: `bitbadges-cli sdk skills prediction-market` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/prediction-market - -## Category - -`token-type` - diff --git a/skills/build/product-catalog/SKILL.md b/skills/build/product-catalog/SKILL.md deleted file mode 100644 index 1a1b28d..0000000 --- a/skills/build/product-catalog/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Multi-product storefront with per-product pricing, supply limits, and optional burn-on-purchase. Each product is a separate token ID. ---- - - - -# Products - -Multi-product storefront with per-product pricing, supply limits, and optional burn-on-purchase. Each product is a separate token ID. - -## When to use this skill - -Required standards: ["Products"] - -- N token IDs (one per product), starting at 1 -- N+1 approvals: 1 purchase approval per product + 1 optional burn approval -- Each purchase approval: fromListId="Mint", toListId="All" (or burn address if burn-on-purchase), 1 coinTransfer paying the store address -- Payment goes directly to store address (NOT to escrow) — overrideFromWithApproverAddress: false -- Each product has independent price, supply limit (maxNumTransfers), and burn-on-purchase toggle -- predeterminedBalances.incrementedBalances.startBalances: 1x of that product's token ID - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "product-catalog"`. -- **CLI**: `bitbadges-cli sdk skills product-catalog` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/product-catalog - -## Category - -`token-type` - diff --git a/skills/build/quest/SKILL.md b/skills/build/quest/SKILL.md deleted file mode 100644 index 544e00a..0000000 --- a/skills/build/quest/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Quest/reward collection — users complete criteria and claim a badge + coin payout ---- - - - -# Quest - -Quest/reward collection — users complete criteria and claim a badge + coin payout - -## When to use this skill - -Required standards: ["Quests"] - -- Single token only: validTokenIds = [{start: "1", end: "1"}] -- Quest approval MUST be properly gated — typically via an off-chain claim (merkle challenge with claimConfig), but can also use on-chain criteria (mustOwnTokens, dynamicStoreChallenges, evmQueryChallenges, votingChallenges) -- Coin transfers with overrideFromWithApproverAddress: true + overrideToWithInitiator: true -- predeterminedBalances: amount 1, no increments, no recurring, no duration -- Escrow funded upfront via set_mint_escrow_coins (rewardAmount * maxClaims) -- invariants.noCustomOwnershipTimes: true - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "quest"`. -- **CLI**: `bitbadges-cli sdk skills quest` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/quest - -## Category - -`token-type` - diff --git a/skills/build/smart-token/SKILL.md b/skills/build/smart-token/SKILL.md deleted file mode 100644 index 8cc200e..0000000 --- a/skills/build/smart-token/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: IBC-backed smart token with 1:1 backing and two required approvals (backing + unbacking) ---- - - - -# Smart Token - -IBC-backed smart token with 1:1 backing and two required approvals (backing + unbacking) - -## When to use this skill - -Required standards: ["Smart Token"] - -- MUST include cosmosCoinBackedPath in invariants with conversion sideA/sideB -- MUST configure at least one alias path (decimals must match IBC denom decimals) -- MUST create TWO required collection approvals (backing + unbacking). Transferable approval is COMMON but OPTIONAL: - 1. Backing approval (REQUIRED): fromListId = backing address, allowBackedMinting: true, mustPrioritize: true - 2. Transferable approval (OPTIONAL — include for wrapped assets, omit for vaults/escrows): fromListId = "!Mint", toListId = "All" - 3. Unbacking approval (REQUIRED): toListId = backing address, allowBackedMinting: true, mustPrioritize: true - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "smart-token"`. -- **CLI**: `bitbadges-cli sdk skills smart-token` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/smart-token - -## Category - -`token-type` - diff --git a/skills/build/subscription/SKILL.md b/skills/build/subscription/SKILL.md deleted file mode 100644 index a94f807..0000000 --- a/skills/build/subscription/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Time-based subscription token with recurring payment approvals and auto-deletion on expiry ---- - - - -# Subscription - -Time-based subscription token with recurring payment approvals and auto-deletion on expiry - -## When to use this skill - -Required standards: ["Subscriptions"] - -- validTokenIds: MUST be exactly one token ID [{ "start": "1", "end": "1" }] -- Subscription faucet approval requirements: - - fromListId: "Mint" - - overridesFromOutgoingApprovals: true - - coinTransfers: at least 1 entry, both override flags false - - predeterminedBalances.incrementedBalances.durationFromTimestamp: MUST be non-zero (duration in ms) - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "subscription"`. -- **CLI**: `bitbadges-cli sdk skills subscription` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/subscription - -## Category - -`token-type` - diff --git a/skills/build/tradable/SKILL.md b/skills/build/tradable/SKILL.md deleted file mode 100644 index 538ff13..0000000 --- a/skills/build/tradable/SKILL.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: NFT marketplace standard enabling peer-to-peer transfers with the 'NFTMarketplace' standard tag and NFTPricingDenom ---- - - - -# Tradable NFTs - -NFT marketplace standard enabling peer-to-peer transfers with the "NFTMarketplace" standard tag and NFTPricingDenom - -## When to use this skill - -Required standards: ["NFTMarketplace", "NFTs", "NFTPricingDenom:ubadge"] - -- MUST include all three standards together -- NFTPricingDenom format: "NFTPricingDenom:" (sets pricing denomination for orderbook) -- MUST include a free transfer approval: fromListId: "!Mint", toListId: "All", initiatedByListId: "All", approvalId: "transferable-approval" -- Enables orderbook/marketplace integration -- Typically used with NFT collections -- Note: Legacy names "Tradable" and "DefaultDisplayCurrency" are still accepted for existing collections - -## Get the full instructions - -The canonical instructions for this skill live in the BitBadges SDK and are loaded on demand. Use one of these to fetch them: - -- **MCP tool (preferred in Claude Code)**: call `get_skill_instructions` with `id: "tradable"`. -- **CLI**: `bitbadges-cli sdk skills tradable` -- **Web docs**: https://docs.bitbadges.io/x-tokenization/examples/skills/tradable - -## Category - -`standard` - diff --git a/skills/operations/claim/SKILL.md b/skills/claim/SKILL.md similarity index 100% rename from skills/operations/claim/SKILL.md rename to skills/claim/SKILL.md diff --git a/skills/operations/explain/SKILL.md b/skills/explain/SKILL.md similarity index 100% rename from skills/operations/explain/SKILL.md rename to skills/explain/SKILL.md diff --git a/skills/operations/query/SKILL.md b/skills/query/SKILL.md similarity index 100% rename from skills/operations/query/SKILL.md rename to skills/query/SKILL.md diff --git a/skills/operations/review/SKILL.md b/skills/review/SKILL.md similarity index 100% rename from skills/operations/review/SKILL.md rename to skills/review/SKILL.md diff --git a/skills/operations/simulate/SKILL.md b/skills/simulate/SKILL.md similarity index 100% rename from skills/operations/simulate/SKILL.md rename to skills/simulate/SKILL.md From deb460b4f57e0af65119f7a482aeb28434c963fa Mon Sep 17 00:00:00 2001 From: Trevor Miller Date: Sun, 26 Apr 2026 13:31:32 -0400 Subject: [PATCH 4/4] Add marketplace.json + tighten validate workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit marketplace.json was the only real blocker for `/plugin marketplace add BitBadges/bitbadges-plugin` to work. Without it, CC may reject the repo or treat it as a single-plugin source rather than a registered marketplace listing. Schema confirmed against https://code.claude.com/docs/en/plugin-marketplaces.md — single-plugin repo with source pointing at "./". While in there, tighten the CI validate workflow: - Validate marketplace.json + hooks/hooks.json JSON syntax (was only plugin.json + .mcp.json) - Check marketplace.json required fields (name, owner.name, plugins[0] has name + source) - Frontmatter check now also covers commands/*.md (was skills only) - New check: referenced scripts (doctor.sh, prewarm.sh) exist, are executable, and pass `bash -n` syntax check - New check: agent frontmatter has required name + description Subagent frontmatter `model: inherit` confirmed valid (it's the default when omitted), so agents/bitbadges-builder.md needs no change. All MCP tool names referenced in skills (set_standards, add_approval, simulate_transaction, review_collection, validate_transaction, get_skill_instructions, explain_collection, set_invariants, add_alias_path, set_permissions, set_valid_token_ids, set_collection_metadata, build_claim, query_collection, query_balance, verify_ownership) verified against the SDK builder source — all 16 exist. CLI command references (sdk skills, sdk review, sdk interpret-tx, sdk address convert, sdk alias for-*, sdk docs, sdk status) verified against src/cli/commands/sdk.ts — all present. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude-plugin/marketplace.json | 35 ++++++++++++++++++++++ .github/workflows/validate.yml | 53 ++++++++++++++++++++++++++------- 2 files changed, 77 insertions(+), 11 deletions(-) create mode 100644 .claude-plugin/marketplace.json 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