Skip to content

Claude Code Plugin

Install and use the BitBadges Claude Code plugin. It wires the MCP builder tools and adds 8 workflow skills, two slash commands, and a builder subagent.

The Claude Code plugin is a convenience layer on top of the chain binary and CLI for Claude Code users. It registers the bitbadges-builder MCP server and ships 8 skills that teach Claude how to use the CLI, the MCP tools, and the docs for common workflows.

sh
curl -fsSL https://install.bitbadges.io | sh
bb settings set apiKey "$BITBADGES_API_KEY"
text
/plugin marketplace add BitBadges/bitbadges-plugin
/plugin install bitbadges
/bitbadges:setup

The plugin is a thin harness, not a knowledge base. Token-type instructions live in the SDK and surface through bb dev skills smart-token (one command per skill id), the get_skill_instructions MCP tool, and the Skills pages. The plugin's job is to teach Claude where to find them and how to compose them, not to ship one wrapper per token type.

Prerequisites

The combined installer provides bb, the chain binary, and the SDK commands. The SDK package provides bitbadges-cli and bitbadges-builder. Offline building needs the SDK CLI; native Cosmos commands need the chain binary. MCP is optional for CLI work. Configure API access for remote operations when needed.

The plugin uses installed binaries and does not download a fallback. If a command is missing, /bitbadges:setup identifies the prerequisite for the task instead of treating every optional capability as a blocker.

Run /bitbadges:setup once to confirm the wiring, and /bitbadges:status for a health check at any time.

What You Get

MCP Server (Auto-Wired)

The plugin's .mcp.json registers bitbadges-builder, so there is no claude mcp add step:

json
{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "bitbadges-builder",
      "args": []
    }
  }
}

The server runs the same SDK version as the installed CLI. If the client cannot find it, check its PATH or configure the absolute binary path. A running MCP server is not necessary to use the CLI skills.

Skills (8)

Each skill routes Claude to the right CLI command, MCP tool, or docs page for one workflow. None duplicates token-type knowledge from the SDK.

SkillWhat it teaches
buildDiscovers standards with bb dev skills, loads the installed schema and examples, and constructs with CLI presets. Uses MCP as an optional adapter
reviewAudit a transaction file or live collection for correctness, standards compliance, approval ordering, and UX issues. Wraps bb check and review_collection
simulateDry-run a transaction. Returns events and per-address balance diffs. Always before broadcast. Wraps simulate_transaction
explainPlain-English description, audience-aware (user, developer, auditor). Wraps explain_collection and bb explain
queryCollections, balances, accounts, claims, standards, and every API route. Discovers routes with --help-json first, then calls
addressAll six address operations: cosmos and EVM conversion, IBC backing, wrapper, mint-escrow, and alias derivations
claimBuild or audit an open, code-gated, password-gated, or whitelist-gated claim. Additional ownership requirements use the appropriate approval primitives
broadcastSign and broadcast. On rails: dry-run by default, explicit confirmation for live. Picks between chain binary, burner, browser bridge, and programmatic signer

For deeper instructions on a specific token type, the plugin sends Claude to the SDK, CLI, or docs rather than redefining them locally.

Slash Commands

CommandWhat it does
/bitbadges:setupChecks prerequisites for the selected task and guides local API configuration without asking for secrets in chat
/bitbadges:statusRuns CLI diagnostics and distinguishes offline readiness from remote connectivity. Live MCP connectivity is checked through client tool discovery

Subagent

bitbadges-builder is a focused builder agent. It uses CLI presets and canonical skills first, with MCP available when useful. It saves the proposal, reviews and simulates it, then chooses the signing path based on wallet ownership and granted authority. Use it for isolation from the main conversation: "Have the bitbadges-builder agent prepare an unsigned smart token proposal for review."

SessionStart Pre-warm Hook

The compatibility hook checks the installed CLI version quietly. It performs no package downloads or configuration changes.

API Key

The CLI configuration is shared with the MCP server. /bitbadges:setup reuses it without printing secrets and directs you to configure a key locally when remote access is needed. Get a key at bitbadges.io/developer. No key is needed for offline proposal construction.

Migrate from a Manual MCP Setup

If you previously registered the server manually, inspect claude mcp list after installing the plugin. Remove only a confirmed duplicate manual registration, using the scope shown by your client; inspect claude mcp remove --help before changing it:

text
claude mcp remove bitbadges-builder

/bitbadges:setup can help inspect the registrations. A matching server name alone does not establish that there is a duplicate.

When You Do Not Need the Plugin

The plugin is for Claude Code only. Other harnesses get the same coverage from the MCP server and the skill docs:

  • Cursor, Claude Desktop, other MCP clients: set up the bitbadges-builder server in your client (MCP Builder Tools). The server exposes get_skill_instructions({ "skillId": "smart-token" }) for on-demand loading, the same path the plugin uses.
  • Generic LLMs, shell scripts, CI: use the CLI. For skill instructions, read the Skills pages or run bb dev skills smart-token.
  • TypeScript developers: npm install bitbadges and use the SDK.

The CLI is the base layer. Skill content is rendered in one place (Skills) and consumed by reference from the plugin, the MCP server, and the CLI.

Source

Edit this page on GitHub

For agents

How agents read these docs