docs

Skills

Skills are policy; the CLI is mechanics.

Each bro capability ships a skill: a markdown policy file that says when and why to use the command. The CLI owns how.

Shipped skills

SkillTriggerPolicy it carries
act/act or a bro: PR #N … status pingRun the review gate until green; fix or defer findings; merge through bro review act merge
agentsSupervise bro-managed agents: respawn a lost worker, stop one, or inspect the agent planePreserve the agent's identity and handles
checkA repo with a Sverka workflow, or a request to run checks/scans through broRun the repository's checks through the Sverka facade
convoy/convoy or a request to run a beads workflowClaim molecule steps atomically and respect human gates
debt/debt or a question about review debt on merged PRsCollect, triage, claim, fix, and sync findings
docsRead or mutate task documents and stores, including the user-level storeKeep task and store verbs predictable; --global selects the user store
drill/drill, /unwind, or a task needing scoped descentNarrow the investigation, return a result, and prevent recurrence
driveOrphaned PRs need an owner, or a request to drive the review loopPoll gates, spawn unowned fixers, and merge only on green
guardA declarative nudge should fire on a hook eventGuards are context, never a gate — dry-run defs with bro self guard test
judgeCalibrated decisions for agent loops — act triage annotation, fallback escalationTyped questions in, typed answers out; judge.mode governs consumers
learnLessons should outlive the session, an artifact needs capture, or the store may know the answerStore trigger-gated lessons with evidence instead of unconditional memory
loopWork the backlog autonomously end-to-endClaim → worktree → agent → gate → close → repeat
next“Work the backlog,” “clean the queue,” /next, or a /goal over open beadsClaim one ready bead and emit its work order
notifyA background worker, watcher, or fixer needs to reach a live sessionWrite mailbox events; let post-tool probes deliver them
providersConfigure or debug the provider registry — kinds, wires, judge.provider, agents.<backend>.providerProviders are configured, never hardcoded; no silent vendor defaults
queryWrite or run a kind = "query" cross-provider GraphQL planRead-only fan-out; no secrets in plans, auth comes from the connector's own login
retroSession end, before the final answer, or when the retro-on-stop guard firesThe session-end checklist: loose ends, hand-rolled mechanics, call economy, lesson capture, debt sweep
sddThe repo enables spec-driven development or asks about missing-spec nudgesPut a written spec before code for claimed work
serveA thin client needs the bro facade over HTTPExpose local agents and fleet snapshots over loopback JSON
stackWork should land as a stacked bead → worktree → PR chainPush beads onto ordered stacks, then sync after merges
statusA thin client needs the live board in one readbro fleet status --json is the contract; --deep adds the act gate
sweep/sweep, or prune/dispose of closed beadsThe burn is gated on harvest — the refusal is the feature
typesafe-aiBuilding features on TypeSafe's System One typed-judgment modelsProgrammable AI primitives — the same models the judge consumes
sync/sync or a request to publish/restore bro artifactsPublish and restore runtime artifacts on the data ref
watchSupervise parallel convoys/agents or ask what needs attentionRead the attention list; keep the heartbeat detached and read-only
workParallel sessions collide in a shared repo or worktrees need cleanupUse sibling worktrees and leave them clean
wtf/wtf or sharp frustration at the agent's own workCapture complaints verbatim and turn retros into prevention work

Adapters and generation

The portable package is the repo root: plugin.json (Agent Plugins) and skills/<name>/SKILL.md (Agent Skills). Every agent reads that pair. Claude and Codex install that root. Their extras are a client manifest and a hook map (plugins/claude/bro/hooks/hooks.json, plugins/codex/bro/hooks/hooks.json), not a second skills/ tree. Cursor and Devin still add those extras under plugins/<client>/bro. OpenCode, Kilo, and pi are different: they're native plugins installed by bro plugins install <client> — a self-contained module (plugins/<client>/bro/bro.ts) carrying hooks inline, with no skills tree beside it.

scripts/gen-plugins.ts keeps those host extras in step. The CLI bundle embeds a snapshot of skills and formulas at build time. Edit skills/, then use the repository freshness checks before committing generated output.

Skill discipline

Read the governing SKILL.md before running its loop. Waiting mechanics, claim etiquette, failure fallbacks, and gate policy belong there, not in a prompt rewritten from memory.

On this page