# Bb Plugins

Build, install, and debug bb plugins.

- Repository: https://github.com/davidondrej/skills (4238 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add davidondrej/skills --skill bb-plugins -g -a claude-code -y`
Codex: `npx skills add davidondrej/skills --skill bb-plugins -g -a codex -y`
Cursor: `npx skills add davidondrej/skills --skill bb-plugins -g -a cursor -y`
Gemini CLI: `npx skills add davidondrej/skills --skill bb-plugins -g -a gemini-cli -y`

## Description

Build, install, and debug bb plugins. Use when the user wants a bb plugin, a sidebar panel, a bb CLI subcommand, an agent tool, a theme, a provider, or to extend bb itself. For running threads and the core bb CLI, use bb-cli instead.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# bb plugins

bb plugins are TypeScript packages that run inside bb. They are how bb extends itself.

Many first-party features are plugins: GitHub, Docs, Memory, Tasks, Connect, Automations, Secrets, Keep Awake, and the coding-agent providers.

## Trust

Plugins are full-trust. Server code runs in-process. App UI is same-origin page code, not a sandbox. Host workers run as Node on enrolled machines.

Review source before installing third-party plugins. Keep credentials in `secret: true` settings.

## This skill vs others

- Use this skill to create, install, or change a plugin.
- Use `bb-cli` to operate bb (threads, projects, environments).
- For exact API signatures, read the `bb-plugin-authoring` skill if it is available, then run `bb guide plugins`. In the plugin directory, run `bb plugin types` before trusting local SDK types. Do not guess from minified `dist/` files.

## Scaffold

```sh
bb plugin new hello            # add --app for a React UI
cd bb-plugin-hello
bb plugin install . --yes
bb plugin dev                  # rebuild + reload on save
```

The manifest is the `bb` object in `package.json`. Required: `bb.name`, `bb.description`, `bb.branding.icon`, `bb.server`. Optional: `bb.app`, `bb.host`, `bb.skills`, `bb.themes`.

Plugin id is the last package-name segment with a `bb-plugin-` prefix stripped. `bb-plugin-hello` and `@acme/bb-plugin-hello` both become `hello`.

Put runtime imports in `dependencies`. Leave types and tooling in `devDependencies`. Git installs run `npm install --omit=dev`.

## What a plugin can add

A default-export factory in `server.ts` receives `BbPluginApi` and registers surfaces:

- settings, kv + SQLite storage, HTTP, RPC, realtime
- background services and cron
- one top-level `bb <name> …` command
- agent tools, `skills/` folders, extra instructions
- mention providers
- optional host workers and experimental agent providers

The rest: https://github.com/davidondrej/skills/blob/HEAD/skills/agent-orchestration/bb-plugins/SKILL.md