BB-Skills

AI coding skills enriched with BuildBetter customer evidence.

What is this?

BB-Skills is a collection of AI coding skills you can install into your favorite AI coding agent. Pick the skills you need -- install only the packs that matter for your workflow. BB-Skills works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, and Amazon Q.

Quick start

Option A: npx (fastest, no install)

npx skills add buildbetter-app/BB-Skills

Or install a specific skill:

npx skills add buildbetter-app/BB-Skills --skill trust-but-verify

Option B: bb-skills CLI (pack-based install)

pip install bb-skills
bb-skills install spec-workflow    # spec-driven development skills
bb-skills install testing          # browser testing skills
bb-skills install all              # everything

3. Use them

Skills are installed into your AI coding agent. On platforms with slash commands (Claude Code, Codex, Gemini):

/bb-specify Build a user dashboard with activity feed
/bb-plan
/trust-but-verify

On passive platforms (Cursor, Copilot, Windsurf, Amazon Q), skills are injected as context automatically.

How it works

You run bb-skills install once per machine. The CLI auto-detects which AI coding platforms you have installed (~/.claude/, ~/.codex/, ~/.gemini/, .cursor/, etc.) and copies skills to all of them in the correct format.

To see what platforms are detected:

bb-skills platforms

To install for a specific platform only:

bb-skills install testing --platform claude

To install a single skill instead of a whole pack:

bb-skills install trust-but-verify

Available packs

Platform support

Skill reference

core

spec-workflow

testing

BuildBetter integration

The spec-workflow skills can optionally use BuildBetter's customer evidence API to enrich specifications, plans, and reviews with real customer data. This is not required -- all skills work without it. When a BUILDBETTER_API_KEY environment variable is set, the workflow will automatically pull relevant customer insights, feature requests, and pain points into your specs and plans.

To enable it, set the API key in your shell:

export BUILDBETTER_API_KEY=your_key_here

Evidence collection is best-effort and never blocks the workflow. If the key is missing or the API is unreachable, skills continue normally.

Updating

To update all installed skills to the latest version:

bb-skills update

CLI reference

Contributing

See CONTRIBUTING.md for guidelines on adding skills, writing adapters, and submitting pull requests.

Acknowledgments

BB-Skills was inspired by and originally derived from github/spec-kit (MIT License). BuildBetter has significantly extended the original with customer evidence integration, browser testing skills, multi-platform support, and a skill management CLI.

License

This project is licensed under the MIT License. See LICENSE for details.