bb-skills 1.0.0

Install and manage BB-Skills — AI coding skills enriched with BuildBetter customer evidence.

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 1: Install from GitHub

pip install bb-skills
bb-skills install spec-workflow
bb-skills install testing

Option 2: Clone and install locally

git clone https://github.com/buildbetter-app/BB-Skills.git
cd BB-Skills
pip install -e .
bb-skills install spec-workflow

Option 3: uv (fastest)

uv tool install bb-skills
bb-skills install testing

Available packs

Pack	Skills	Description
core	bb-skills-update	Update checker (auto-included)
spec-workflow	specify, plan, review, tasks, clarify, analyze, checklist, constitution, implement	BuildBetter-enriched spec-driven development
testing	app-navigator, trust-but-verify, generate-tests	Browser-based verification and Playwright test generation

Platform support

Platform	Format	Slash Commands	Install Path
Claude Code	SKILL.md	Yes	~/.claude/skills/
Codex CLI	SKILL.md	Yes	~/.codex/skills/
Cursor	.mdc rules	No (passive)	.cursor/rules/
GitHub Copilot	.instructions.md	No (passive)	.github/instructions/
Gemini CLI	.toml	Yes	~/.gemini/commands/bb-skills/
Windsurf	.md rules	No (passive)	.windsurf/rules/
Amazon Q	.md rules	No (passive)	.amazonq/rules/

Skill reference

core

Skill	Description
bb-skills-update	Checks for available BB-Skills updates via GitHub releases

spec-workflow

Skill	Description
specify	Define what you want to build -- requirements and user stories
plan	Create a technical implementation plan with your chosen tech stack
review	BuildBetter-first usability and code review
tasks	Generate an actionable task list from your implementation plan
clarify	Clarify underspecified areas before planning
analyze	Cross-artifact consistency and coverage analysis
checklist	Generate quality checklists that validate requirements completeness
constitution	Create or update project governing principles
implement	Execute all tasks to build the feature according to the plan

testing

Skill	Description
app-navigator	Map application routes, pages, and components for UI/UX audit
trust-but-verify	Verify UI/UX and functionality match the original plan
generate-tests	Generate reusable Playwright test files from the app map

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

Command	Description
bb-skills install <pack>	Install a skill pack
bb-skills uninstall <pack>	Remove an installed skill pack
bb-skills update	Update all installed packs to latest
bb-skills list	List installed packs and skills
bb-skills platforms	Show supported platforms and install paths

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.