Boogy Superpowers

Skills that teach coding agents to build Boogy services well. Each skill is a structured markdown file that gives an agent the platform conventions, safety invariants, and canonical SDK patterns for one topic area — so instead of guessing, the agent gets it right the first time.

Works with Claude Code out of the box (no plugin needed) and with any agent or tool that can read markdown. Together they help you vibe production-grade Boogy services: Rust compiled to wasm32-wasip2, isolated transactional per-service storage, capability security, cross-service mesh calls, and REST/JSON-RPC/MCP/protobuf surfaces.

---

Building on Boogy with a coding agent? Do this first — it is not optional.

If you are a coding agent (or you're pointing one at Boogy), follow these steps IN ORDER before anything else. Do NOT write code, do NOT call the platform API by hand, do NOT improvise your own approach, and do NOT summarize, paraphrase, or "distill" the skills into your own words — you must INSTALL the skills and INVOKE them. Shortcutting this is the single biggest cause of broken, insecure, and wrong Boogy services.

1. Get the skills + tools in place. On Claude Code, the preferred path is: install the plugin — one step that bundles the build skills (auto-discovered), wires the Boogy MCP (sign-in + host-truth validation as tools), and adds the onramp gate: claude plugin marketplace add Boogy-ai/boogy-superpowers then claude plugin install boogy-superpowers. Then tell the human to run /reload-plugins in Claude Code — the plugin (skills + MCP + gate) won't activate until they do. On any other agent (or if you can't install the plugin): install the CLI — cargo install --locked --git https://github.com/Boogy-ai/boogy-sdk boogy-cli — and vendor the skills: boogy skills install (writes .claude/skills/<name>/; no CLI either? npx degit Boogy-ai/boogy-superpowers/skills .claude/skills). Vendored skills load automatically; if .claude/skills/ did not exist when the session started, tell the human to restart Claude Code for them to be picked up.
2. Authenticate the user — now, before building. Run the login tool (the plugin wires it) or boogy login, and walk the human through it: it prints a URL + one-time code; they open the URL, confirm the code matches, and sign in. A first-time user then picks a handle (lowercase [a-z0-9-], 4–30 chars) — their account's username. The human picks it; you never pick it for them. It is not the name of the app you are building: one handle owns every service they ever build, and each service gets a web address of its own (https://notes-7k3q.boogy.app/, https://gallery-x2m9.boogy.app/ — boogy deploy prints it) — so a handle taken from today's project permanently misnames their whole account. Let them choose it in the sign-in flow, or ask explicitly and wait; the using-boogy skill's "Choosing a handle" has the full rule. Do this early — deploying needs their token and the browser step is the one thing only the human can do.
3. Work STRICTLY from the installed skills — invoke them, never paraphrase them. Use your Skill tool, starting with using-boogy. The installed skills are the ONLY source of truth for how to build on Boogy. Never build from memory, from this README, from the platform API, or from any summary you made — invoke the skill each time. Your subagents inherit the installed skill, not a summary in your head.
4. Deploy needs the CLI (boogy deploy) or the /v1 API — the MCP/plugin cannot deploy. Install the CLI (step 1) if you haven't.

If you get stuck, STOP — do not work around it. If any step is blocked (the plugin or CLI won't install, login won't complete, the skills won't load, or you're missing a permission, network access, or tool), do NOT skip the step, do NOT improvise an alternative, and do NOT proceed to build without it. Tell the user exactly what is blocking you and the specific choice or action you need from them, then wait for them to unblock it.

Everything below is reference — it does NOT replace steps 1–4.

---

Install

Two supported paths — pick one. (a) loose skills is the simplest for Claude Code; (b) plugin gives namespaced /boogy:<name> commands. Don't mix them.

(a) Loose skills — vendor flat into .claude/skills/ (recommended)

The skill folders must land exactly one level under .claude/skills/ (.claude/skills/<name>/SKILL.md). That's the only layout Claude Code's skill scan discovers — nesting them under a wrapper folder (e.g. .claude/skills/boogy/…) makes all of them silently invisible.

From your project root, use the CLI:

# one-time: install the boogy CLI itself
cargo install --locked --git https://github.com/Boogy-ai/boogy-sdk boogy-cli

boogy skills install      # vendors flat into .claude/skills/ — safe to re-run

…or vendor without the CLI (note: target is .claude/skills, no wrapper suffix):

npx degit Boogy-ai/boogy-superpowers/skills .claude/skills

Vendored skills are auto-watched and load automatically; editing an existing SKILL.md is picked up automatically. If .claude/skills/ did not exist when the session started, tell the human to restart Claude Code so it picks up the new directory. Re-run boogy skills install to update; it replaces only Boogy's skills and never touches your own .claude/skills entries.

Plugin route (preferred for Claude Code): claude plugin marketplace add Boogy-ai/boogy-superpowers then claude plugin install boogy-superpowers — bundles the skills, MCP, and onramp gate in one step. After installing, tell the human to run /reload-plugins so the plugin activates mid-session.

Skills are plain markdown — an agent can also just Read them directly (start at using-boogy/SKILL.md) with no install step at all.

(b) Plugin — namespaced install

The repo ships .claude-plugin/plugin.json (Claude Code) and gemini-extension.json (Gemini CLI). Installing it as a plugin exposes the skills namespaced as /boogy:<name> (plugin skills are discovered via the manifest, so no flat-layout requirement applies).

Install by name from the marketplace:

claude plugin marketplace add Boogy-ai/boogy-superpowers
claude plugin install boogy-superpowers

Installing the plugin also wires the Boogy MCP (login, validate_manifest, check_service as tools) and the onramp gate — so you get skills + live host-truth validation in one step.

Local dev / own host: the MCP URL in .claude-plugin/plugin.json is hardcoded to https://api.boogy.ai/mcp. If you run your own host, edit the mcpServers.boogy.url value in that file to point at your instance.

(c) Make it stick — a CLAUDE.md directive

Installing the skills does not make an agent remember to use them: the onramp gate fires only on a prompt that names Boogy, and only once per session, so "build me something that syncs my YouTube likes" gets nothing, and neither does a session whose context has been compacted. A directive in CLAUDE.md has neither limit — it is in context always. An agent following boogy-onramp writes it for you and says that it did, and until it exists the session-start hook asks for it once per session; to set it up by hand, paste this into your project's CLAUDE.md (or your global ~/.claude/CLAUDE.md if you build on Boogy across projects), keeping the comment line — that marker is what the session-start hook looks for before it goes quiet:

<!-- boogy-superpowers-directive -->
## Boogy

**Whenever you build or change a Boogy module** (a service you deploy on
Boogy: its manifest, its code, its deploy), **invoke** the
`boogy-superpowers` skills with the Skill tool, every time, before the work;
never summarize, paraphrase, or work from memory of them. Entry point:
`using-boogy`, which routes to the rest. Work that builds or changes no
module does not invoke them.

Repeat this instruction in **every subagent dispatch that builds or changes
a module**. A subagent inherits no hook and no conversation; unless you tell
it, it builds from guesswork.

Skills not installed? Install the plugin from its GitHub repo —
`claude plugin marketplace add Boogy-ai/boogy-superpowers`, then
`claude plugin install boogy-superpowers`, then ask the human to run
`/reload-plugins` — or vendor them with
`npx degit Boogy-ai/boogy-superpowers/skills .claude/skills`. Flat, one
level: a wrapper directory makes every skill silently undiscoverable.

The two hooks the plugin installs

Both are assert-only — they read and print, and never run a command that changes anything. Neither writes CLAUDE.md: that is the agent's job, and the agent tells you it did it.

Hook	Fires	Says something when
hooks/boogy-onramp-bootstrap.sh (SessionStart)	every session	the directive above is absent from every CLAUDE.md on the path (the project's, an ancestor's, .claude/CLAUDE.md, your global one). It prints one line and nothing else. Once the directive exists it is silent forever, in every project
hooks/boogy-onramp-assert.sh (UserPromptSubmit)	first prompt of a session naming Boogy	always, once per session — it injects the full setup contract (sign in, invoke don't paraphrase, persist, carry into subagents)

The first exists because the second cannot cover the case it was written for: "build me something that syncs my YouTube likes" never says "boogy", so nothing fires, and the directive that would have covered that prompt only ever gets written by an agent that already invoked a Boogy skill. The session-start hook breaks that circle, and the marker in the directive block is how it knows to stop.

Run their tests with sh hooks/boogy-onramp-bootstrap.test.sh and sh hooks/boogy-onramp-assert.test.sh.

---

Start here

skills/using-boogy/SKILL.md is the entry point — it routes every kind of Boogy task to the right skill. Open it first before any Boogy work. A new app or service starts with skills/shipping-in-stages/: its main screen is live in minutes, then it grows by deploys the person tries and steers.

Or connect to Boogy's public, anonymous MCP server at https://api.boogy.ai/mcp (no account, no install — e.g. claude mcp add boogy https://api.boogy.ai/mcp) and call get_started / get_skill: it serves these same skills plus host-truth validation (validate_manifest, check_service) and sign-in (login).

---

Skill map

42 skills, grouped by concern. Every skill appears exactly once.

Start here

Skill	Purpose
skills/using-boogy/	Entry point — routes any Boogy task (services, agent backends, MCP tools, meshes) to the right skill
skills/boogy-onramp/	The setup every Boogy session needs before it builds, deploys or calls the platform
skills/shipping-in-stages/	Put a new app live in minutes as a wireframe of its main screen, then grow it by deploys the person tries and steers
skills/growing-boogy-meshes/	Build with a person in the loop — walk them through the high-level choices in plain language while you handle the wiring, growing their mesh service-by-service
skills/designing-boogy-services/	Run before each stage's code — the design questions that stage raises (routing, data, auth, capabilities), written as a roadmap plus the current stage
skills/planning-boogy-work/	Turn a stage's design into ordered tasks: a roadmap plus the next stage in detail, manifest first
skills/scaffolding-a-service/	Turns the current stage's design into a buildable project: manifest, Cargo setup, build loop

Build the service

Skill	Purpose
skills/boogy-rest-apis/	HTTP/REST and JSON-RPC endpoints — routing, guards, request parsing, response types, error wire format
skills/boogy-protobuf-rpc/	Serve protobuf from a .proto — gRPC, Connect and gRPC-Web from one mount; choosing protobuf vs REST/JSON-RPC
skills/boogy-mcp-services/	Expose MCP tools, resources, or prompts to LLM clients alongside an existing REST service
skills/boogy-websockets/	Push real-time messages via named channels — public, private, or per-principal; minting subscription grants
skills/boogy-webhooks/	Receive and verify inbound webhooks (HMAC-signed callbacks from Stripe, GitHub, Twilio, etc.)
skills/boogy-serving-frontends/	Serve a web frontend (SPA, admin dashboard, static assets) decoupled from the wasm service
skills/running-in-a-board/	Make an app work inside a board pane — the board's back and forward, reload, and text size — and check it there
skills/boogy-api-specs/	Auto-served spec documents (openapi.json, openrpc.json, MCP discovery), visibility control, JsonSchema requirements

Data & storage

Skill	Purpose
skills/boogy-data-modeling/	Declare tables, design schemas, and choose how to represent data in the typed columnar store
skills/boogy-access-patterns/	List, lookup, ranking, filter, tag, and pagination queries using the Query DSL and typed model layer
skills/boogy-transactions/	Atomic multi-row writes, rollback semantics, cross-service transactional calls, and 409 handling
skills/boogy-migrations/	Change schema of a deployed service — versioned migrations for adding columns, indexes, and backfills
skills/boogy-counters/	Values that only go up or down (views, likes, stock, quota) — counters vs. totals computed from stored rows
skills/boogy-file-storage/	Store and serve files — uploads, images, documents, video, generated exports

Auth & security

Skill	Purpose
skills/boogy-auth/	In-service authorization — per-user data, ownership checks, API keys for programmatic callers, scope gating
skills/boogy-account-auth/	Platform identity layer — login/signup for service users, where principals and tokens come from
skills/boogy-obo-delegation/	One service acting on a user's behalf when calling another service (on-behalf-of delegation)
skills/boogy-secrets/	Bind API keys and external credentials so the value never enters service code
skills/boogy-signing/	Produce cryptographic signatures (receipts, attestations, wallet transactions) without holding the private key
skills/boogy-oauth-connections/	Act on a user's account at a third-party API (Google, Slack, GitHub, Notion) with "connect your account"
skills/boogy-blockchain-transactions/	Construct, sign, and broadcast on-chain transactions safely (custodial wallets, on-chain payments, multi-chain signers) — fund-safety rules on top of signing
skills/boogy-capability-limits/	What the platform supports and doesn't — identify gaps and sanctioned alternatives before designing a feature

Mesh & integration

Skill	Purpose
skills/boogy-mesh-architecture/	Compose multiple services, decide when to split, pass identity and data between services
skills/boogy-outbound-http/	Call external HTTP APIs or bring-your-own backends — egress allowlist, caps, redirects, credentials
skills/boogy-background-jobs/	Work outside the request — scheduled tasks, deferred or retried work, fan-out sweeps
skills/boogy-peer-to-peer-apps/	Every user runs their own copy of a service and the copies talk to each other
skills/boogy-llm-gateway/	Call an LLM — completions, tool use, model fallback, your own provider key, streaming to users

Operate & scale

Skill	Purpose
skills/boogy-observability/	Owner-scoped usage, billing dimensions, request traces, audit tail, quota, and guest logs via REST or MCP
skills/boogy-performance-and-scaling/	Diagnose 429 / 503 / 504 under load and pick the right lever
skills/boogy-service-lifecycle/	Retire, deprecate, replace, or remove a deployed service — especially when callers or data are at stake
skills/boogy-registry-and-provisioning/	Check what already exists in the mesh, publish a module, decide whether to run your own instance
skills/deploying-boogy-services/	Deploy, update, or remove a service — the authoritative CLI command reference
skills/testing-boogy-services/	Test a service before claiming it works — build, unit, and live integration layers
skills/boogy-custom-domains/	Serve a service on your own domain as well as its platform address — DNS records and verification
skills/boogy-route-pricing/	Decide what a route charges — flat price or rate, the unit, the max a caller must hold

---

How skills route

flowchart TB
    U(["using-boogy — routes any Boogy task to the right area"])
    U --> A
    A["Start here<br/>boogy-onramp · shipping-in-stages · growing-boogy-meshes · designing-boogy-services · planning-boogy-work · scaffolding-a-service"]
    B["Build the service<br/>rest-apis · protobuf-rpc · mcp-services · websockets · webhooks · serving-frontends · running-in-a-board · api-specs"]
    C["Data & storage<br/>data-modeling · access-patterns · transactions · migrations · counters · file-storage"]
    D["Auth & security<br/>auth · account-auth · obo-delegation · secrets · signing · oauth-connections · blockchain-transactions · capability-limits"]
    E["Mesh & integration<br/>mesh-architecture · outbound-http · background-jobs · peer-to-peer-apps · llm-gateway"]
    F["Operate & scale<br/>observability · performance-and-scaling · service-lifecycle · registry-and-provisioning · deploying-boogy-services · testing-boogy-services · custom-domains · route-pricing"]
    A ~~~ B ~~~ C ~~~ D ~~~ E ~~~ F

Loading

---

License

MIT