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
Option C: Codex plugin package
This repo also includes a Codex plugin package at plugins/bb-skills/ plus a repo-local marketplace entry at .agents/plugins/marketplace.json. The plugin bundles the same BB-Skills prompts for Codex and includes Playwright MCP wiring for the browser-testing skills.
Option D: BuildBetter MCP/CLI plugins
This repo includes separate BuildBetter MCP/CLI plugins for Codex and Claude Code under plugins/buildbetter-codex/ and plugins/buildbetter-claude/. They are separate packages because Codex and Claude Code use different plugin manifest directories and remote MCP config schemas.
Codex:
codex plugin marketplace add buildbetter-app/BB-Skills --ref main --sparse .agents/plugins --sparse plugins/bb-skills --sparse plugins/buildbetter-codex
codex plugin add buildbetter@buildbetter
Claude Code:
claude plugin marketplace add buildbetter-app/BB-Skills --sparse .claude-plugin plugins/buildbetter-claude
claude plugin install buildbetter@buildbetter
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
| Pack | Skills | Description |
|---|
core | bb-skills-update | Update checker (auto-included) |
spec-workflow | bb-specify, bb-plan, bb-review, bb-tasks, bb-clarify, bb-analyze, bb-checklist, bb-constitution, bb-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 |
|---|
| bb-specify | Define what you want to build -- requirements and user stories |
| bb-plan | Create a technical implementation plan with your chosen tech stack |
| bb-review | BuildBetter-first usability and code review |
| bb-tasks | Generate an actionable task list from your implementation plan |
| bb-clarify | Clarify underspecified areas before planning |
| bb-analyze | Cross-artifact consistency and coverage analysis |
| bb-checklist | Generate quality checklists that validate requirements completeness |
| bb-constitution | Create or update project governing principles |
| bb-implement | Execute all tasks to build the feature according to the plan |
testing
