BuildBetter Skills

AI coding skills enriched with BuildBetter customer evidence.

---

What is this?

BuildBetter 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. BuildBetter 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/skills

Or install a specific skill:

npx skills add buildbetter-app/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/skills/ plus a repo-local marketplace entry at .agents/plugins/marketplace.json. The plugin bundles the same BuildBetter Skills prompts for Codex and includes Playwright MCP wiring for the browser-testing skills.

codex plugin marketplace add buildbetter-app/skills --ref main --sparse .agents/plugins --sparse plugins/skills --sparse plugins/buildbetter-codex
codex plugin add skills@buildbetter

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 include BuildBetter-specific skills for MCP routing, customer voice, synthetic research, native surveys, Smart Tags, project triage, and knowledge gaps. 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/skills --ref main --sparse .agents/plugins --sparse plugins/skills --sparse plugins/buildbetter-codex
codex plugin add buildbetter@buildbetter

Claude Code:

claude plugin marketplace add buildbetter-app/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

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

BuildBetter 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.