Add skills, slash commands, agent, doctor, and SessionStart pre-warm

.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"
+    }
+  ]
+}

.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

CHANGELOG.md

@@ -6,3 +6,16 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th
 
 ### Added
 - Initial scaffolding: plugin manifest, MCP server registration, README, LICENSE.
+- 8 skills, all hand-written as routing guides on top of the CLI / MCP / docs (no duplicated SDK content):
+  - `build` — meta-guide for constructing any token type. Routes Claude to `bitbadges-cli sdk skills <id>` 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 <id>`, 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.

README.md

@@ -1,35 +1,53 @@
 # BitBadges Plugin for Claude Code
 
-A Claude Code plugin that auto-wires the BitBadges builder MCP server and ships curated skills for token creation, review, simulation, and on-chain queries.
+A Claude Code plugin that auto-wires the BitBadges builder MCP server and teaches Claude how to leverage the BitBadges CLI + docs to build, review, simulate, and query tokens.
 
-## Install
+The plugin is a thin **harness on top of the CLI**. It does not redefine token types or duplicate skill content — every workflow ultimately routes to `bitbadges-cli` commands, the `bitbadges-builder` MCP, or the public docs at https://docs.bitbadges.io. Source of truth stays in the SDK; the plugin just makes Claude reach for the right tool at the right time.
 
-```
-/plugin marketplace add BitBadges/bitbadges-plugin
-/plugin install bitbadges
-```
+## Prerequisites
 
-That's it. After install, you have:
+The BitBadges chain binary + CLI are the canonical way to interact with BitBadges. Install them first:
 
-- **MCP tools** — `bitbadges-builder` registered automatically (no `claude mcp add` step).
-- **~29 skills** — token creation (smart-token, fungible, NFT, subscription, vault, claim, quest, auction, …), review, simulate, explain, query, address, broadcast.
-- **2 slash commands** — `/bitbadges:setup` and `/bitbadges:status`.
+```sh
+curl -fsSL https://install.bitbadges.io | sh
+```
 
-The plugin uses `npx -y -p bitbadges bitbadges-builder` under the hood, so the latest published `bitbadges` npm package is fetched on first use. No separate install of the JS CLI is required.
+This installs `bitbadgeschaind` (the chain binary) and `bitbadges-cli` (the JS CLI that exposes 104+ API routes plus the `bitbadges-builder` MCP server). This plugin is a Claude Code convenience layer on top of those — it does not replace them.
 
-## What you can do without setup
+Get an API key at [bitbadges.io/developer](https://bitbadges.io/developer) and configure it once:
 
-The MCP server alone covers the vast majority of CC workflows: build a token, review a transaction, simulate a broadcast, query a collection, derive an address. None of these need the chain binary.
+```sh
+bitbadges-cli config set apiKey YOUR_KEY
+```
 
-## What needs `/bitbadges:setup`
+## Install the plugin
 
-Local key management and live transaction broadcasts use the `bitbadgeschaind` chain binary, which is a separate Go binary. Run:
+After the prerequisites above:
 
 ```
-/bitbadges:setup
+/plugin marketplace add BitBadges/bitbadges-plugin
+/plugin install bitbadges
 ```
 
-This walks through installing `bitbadgeschaind` via `https://install.bitbadges.io` (with consent prompt — never auto-pipes to sh) and configures your API key.
+Then run `/bitbadges:setup` once to verify everything is wired and `/bitbadges:status` whenever you want a health check.
+
+## What the plugin adds
+
+- **MCP tools** — `bitbadges-builder` registered automatically (no separate `claude mcp add` step). Exposes 50+ session-based per-field token construction tools, queries, validation, review, and simulation.
+- **8 skills** — guides that route Claude to the right CLI command, MCP tool, or docs page for each common BitBadges workflow:
+  - `build` — meta-guide for building any token type. Discovers via `bitbadges-cli sdk skills`, loads canonical instructions from the SDK, constructs via per-field MCP tools.
+  - `review`, `simulate`, `explain` — pre-broadcast safety net. Wraps `bitbadges-cli sdk review`, MCP `simulate_transaction`, and `bitbadges-cli sdk interpret-collection`.
+  - `query`, `address`, `claim` — runtime ops. Wraps the API routes, address derivations, and claim builder respectively.
+  - `broadcast` — hard-railed signer. Dry-run by default, explicit confirmation for live.
+- **2 slash commands** — `/bitbadges:setup` (one-time prereq check + API key wiring) and `/bitbadges:status` (health check).
+- **`bitbadges-builder` subagent** for focused builder loops.
+- **SessionStart pre-warm** so the first MCP-tool call doesn't pay npx download latency.
+
+The skills don't duplicate token-type knowledge from the SDK. They tell Claude *where* to find that knowledge (CLI / MCP / Gitbook) and *how* to combine it. The full Gitbook docs at https://docs.bitbadges.io are also fair game — fetch what you need.
+
+## Fallback behavior
+
+If `bitbadges-cli` and `bitbadges-builder` aren't on your PATH (because you skipped the prerequisites), the plugin falls back to `npx -y -p bitbadges bitbadges-builder` for the MCP server. This works for read-only LLM workflows but is a degraded path — a globally installed CLI is faster, more reliable, and what `/bitbadges:setup` will recommend.
 
 ## API key
 

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.

commands/setup.md

@@ -0,0 +1,26 @@
+---
+description: One-time setup for the BitBadges plugin — checks prerequisites, configures the API key, and optionally installs the chain binary.
+argument-hint: (no arguments)
+---
+
+# /bitbadges:setup
+
+Verifies that the BitBadges chain binary + CLI are installed (these are the canonical entrypoint — the plugin is a convenience layer on top) and that an API key is configured. Run this once after installing the plugin.
+
+The chain + CLI install is **the** entrypoint. The plugin's `npx`-based MCP fallback only exists as graceful degradation for users who haven't run the install one-liner yet.
+
+## What it does
+
+1. **Chain binary check (required).** If `bitbadgeschaind` is on PATH, print the version. If not, print the install one-liner (`curl -fsSL https://install.bitbadges.io | sh`) and ask for explicit consent before running it. Never auto-pipe `curl ... | sh` — show the command, wait for "yes".
+2. **CLI check (required).** Same flow — if `bitbadges-cli` is on PATH, OK; otherwise the same one-liner installs both binaries together. The presence of `bitbadges-cli` globally also means the `bitbadges-builder` MCP bin is on PATH, which is faster and more reliable than the plugin's npx fallback.
+3. **API key (required).** If `~/.bitbadges/config.json` already has an `apiKey`, use it — no prompt. The CLI config is canonical; both the CLI and the plugin read from there. Otherwise prompt for the key and write via `bitbadges-cli config set apiKey <KEY>`. Source: https://bitbadges.io/developer.
+4. **Migration check (optional).** If the user previously ran `claude mcp add bitbadges-builder ...` manually (user scope), that registration coexists with the plugin's `.mcp.json` entry and produces duplicate MCP servers. Detect it (`claude mcp list | grep bitbadges-builder`) and offer to run `claude mcp remove bitbadges-builder` to clean up.
+
+## Behavior summary for Claude
+
+- Run `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh --json` to enumerate current state.
+- Walk steps 1–4 in order. The chain binary + CLI install is the FIRST thing — don't skip it on the assumption "MCP via npx is good enough".
+- For each missing prerequisite, **show** the command but do not run it without explicit "yes" from the user.
+- End with a one-line summary: "Ready to go" or "X step(s) skipped — re-run /bitbadges:setup when you want to address them".
+
+Do not store the API key in the plugin's `userConfig` keychain — write it to the CLI config so it works for everything: CLI, MCP, plugin, manual scripts.

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.

hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/prewarm.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}