Add skills, slash commands, agent, doctor, and SessionStart pre-warm#1
Merged
Add skills, slash commands, agent, doctor, and SessionStart pre-warm#1
Conversation
…Start hook
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 <id>`. 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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
The 22 generated SKILL.md files in skills/build/<id>/ duplicated content
already available via `bitbadges-cli sdk skills <id>`, 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 <id>` 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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First content drop for the BitBadges Claude Code plugin. After this PR merges,
/plugin install bitbadgesgives a Claude Code user 22 generated token-creation skills, 7 hand-written operational skills, 2 slash commands, a builder subagent, an environment doctor, and a SessionStart pre-warm hook.Files
Generated SKILL.md (22) — one per SDK
SKILL_INSTRUCTIONSid. Thin routing wrappers; substance is fetched on-demand. Generated bybitbadgesjs/packages/bitbadgesjs-sdk/scripts/gen-llm-mirrors.ts(separate PR in bitbadgesjs).Hand-written skills (7):
review,simulate,explain,query,address,claim,broadcast. Each is on-rails — explicit failure modes, hard don'ts, and clear routing back to/bitbadges:setupwhen prerequisites are missing. Thebroadcastskill in particular has hard rails since it's the only skill that touches money.Slash commands (2):
/bitbadges:setup— one-time prereq check + API key wiring. Reads~/.bitbadges/config.jsonfirst (CLI is canonical) before prompting. Never auto-pipescurl|sh./bitbadges:status— quick health check viadoctor.sh.Agent:
bitbadges-buildersubagent definition — primed to reach for MCP tools first, fall back to CLI, only touch the chain binary for live broadcasts.Scripts:
scripts/doctor.sh— environment diagnostic powering both slash commands. JSON or human output. Detects chain binary, CLI (or via npx), API key, network, and API connectivity.scripts/prewarm.sh— silent best-effort npx cache warm. Exits 0 even if npx is missing or network is offline.Hooks:
hooks/hooks.json—SessionStartrunsprewarm.shso the first MCP-tool call doesn't pay 5–15s of npm download.Decisions baked in (per backlog #0342)
bitbadges(notbitbadges-builder, notbb). Brand-aligned, matches the npm package, slash form/bitbadges:create-smart-tokenreads naturally.~/.bitbadges/config.json) is canonical. Plugin reads from it; only prompts for keychain when no existing config is found.SessionStartpre-warm hook ships in v0.1 (best UX wins).Test plan
claude plugin validate .passes (CI runs this).bash scripts/doctor.shruns and reports correctly on a clean machine — verified locally on a machine with the chain binary + CLI installed./plugin marketplace add BitBadges/bitbadges-pluginthen/plugin install bitbadgesend-to-end works on a clean container.bitbadges-builderMCP tools appear via the plugin without a separateclaude mcp addstep.🤖 Generated with Claude Code