Author BB plugins

A BB plugin is a TypeScript package that can add server behavior, agent capabilities, host-rendered UI, or a frontend bundle.

Use the current SDK types and repository source as the contract. This skill routes to detailed references, but the installed BB version decides the exact API.

Implement and verify

Inspect the affected package and current SDK declarations to select backend, frontend, or both. Build the plugin and verify the affected contracts and user workflow. Install or reload when a live check is needed for the requested work.

To find where a plugin can extend the app, open the Plugin Guide in bb or at https://getbb.app/plugin-guide.

Use bb plugin new <name> for a new plugin. The scaffold includes frontend files. Remove bb.app and those files when the plugin is headless.

Every new public Plugin SDK surface starts with an experimental_ prefix and an entry in docs/api_to_audit.md. Add its Plugin Guide card and API inventory in the same change.

Read only the relevant reference

Start, package, and release

• Read references/quickstart.md for the first plugin, manifest fields, branding, plugin ids, builds, installs, and dependencies.
• Read references/distribution.md for exact API lookup, updates, Git or npm release, multi-plugin repositories, custom marketplaces, and store text.

Backend

• Read references/backend-foundation.md for the factory (and which reference covers each bb.* member), logging, settings, storage, server information, and host entries.
• Read references/backend-sdk.md for the bb.sdk area map, threads, plugin metadata, files, terminals, attachments, and calls to another plugin's RPC.
• Read references/backend-api-index.md to check every public backend, host, AI-service, and test export.
• Read references/backend-events.md for lifecycle events, the dispatch hook, environment providers, HTTP, RPC, realtime, background services, and schedules.
• Read references/backend-machines.md for machine providers, core project source setup, enrollment/bootstrap helpers, and server access.
• Read references/backend-cli-agents.md for CLI commands, input forms, agent tools, agent configuration, and helper AI services.
• Read references/providers.md only when the plugin registers an agent provider or contributes provider environment variables. Its contract lives in docs/provider-plugin-api.md and docs/provider-bridge-protocol.md in the bb repository.
• Read references/provider-bridge-api-index.md to check every public provider bridge, bridge-test, and ACP export.
• Read references/backend-ui-lifecycle.md for host-rendered UI, status, cleanup, and reload behavior.

Frontend

• Read references/frontend-registration.md for definePluginApp, thread header and Browser toolbar controls, sidebar replacement, and the provider directory.
• Read references/frontend-sidebar-navigation.md for navigation providers (rail or list placement) and controls beside the sidebar toggle.
• Read references/frontend-api-index.md to check every public frontend runtime value and type export.
• Read references/frontend-core-slots.md for trusted content scripts, homepage, settings, navigation, thread panels, environment and machine provider inputs, interactions, sidebar actions, and file openers.
• Read references/frontend-renderer-slots.md for source, diff, message, timeline, palette, and provider-icon renderers or actions.
• Read references/frontend-components.md for ThreadChat, provider controls, source and diff viewers, links, panels, the new-thread composer, and shared icons.
• Read references/frontend-hooks-and-ui.md for hooks, composer customization, vendored components, runtime shims, crash isolation, and styling.

Testing

• Read references/frontend-testing-api-index.md to check every frontend test runtime value and type export.
• Read references/testing.md before you add tests or run a live plugin loop, and for reference plugins to copy from.

Contract rules

• Parse freeform input at the boundary and pass typed values internally.
• Declare only manifest fields and settings that the plugin implements.
• Keep secret settings on the server.
• Treat frontend parameters and persisted values as untrusted input.
• Return bounded CLI and agent-tool output.
• Document plugin commands, settings, and operating constraints in the plugin's own skills/ directory. The core CLI skill owns generic plugin management, not individual plugin behavior.
• Dispose every service, schedule, listener, content script, and resource.
• Use SDK host components and navigation for host-owned behavior.
• Use vendored UI source for plugin-owned controls.
• Keep experimental names until the public API audit stabilizes them.
• Use current names. Compatibility aliases can warn and can expire after one release. Removed APIs can throw.
• Run bb plugin types when SDK declaration versions can drift.
• Run bb plugin build before install, release, or marketplace submission.

Verification

Confirm the backend contract, frontend contract, manifest, generated bundle, and live behavior that the change affects. Use focused tests for failure-prone policy and lifecycle behavior.