Beads
Guide an AI agent to manage beads (bd) tasks using bd prime for live CLI truth instead of stale inline command docs in SKILL.md.
Overview
Beads is an agent skill most often used in Build (also Ship and Operate) that teaches agents to rely on bd prime and bd --help for CLI truth while applying beads decision frameworks for task workflow.
Install
npx skills add https://github.com/steveyegge/beads --skill beadsWhat is this skill?
- ADR-backed design: bd prime is the single CLI reference source of truth
- SKILL.md trimmed to ~500 words of decision frameworks versus ~3,300 words of duplicated CLI
- Points agents to bd prime (hook-loaded) and bd --help for always-current commands
- resources/ depth for molecules, agents, and gates without token-heavy inline docs
- Eliminates version drift between skill text and installed bd releases
- SKILL.md reduced from ~3,306 words to ~500 words per ADR-0001
- Prior inline CLI reference cited ~2,000+ words in SKILL.md and ~2,363 words in CLI_REFERENCE.md
Adoption & trust: 1k installs on skills.sh; 24.4k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your beads skill loads duplicated CLI docs that drift from the installed bd version and waste context on reference material the tool already generates.
Who is it for?
Solo builders already using or adopting the beads (bd) CLI with hook-loaded bd prime in Claude Code or similar agents.
Skip if: Teams without bd installed who need a generic kanban or GitHub Issues skill with no beads dependency.
When should I use this skill?
The agent should manage or advance beads (bd) tasks and needs current CLI semantics without loading duplicated reference into context.
What do I get? / Deliverables
Agents pull current bd workflow context via bd prime, use lightweight SKILL guidance for planning patterns, and keep task state accurate across the repo.
- Correct bd command usage grounded in bd prime / --help
- Structured task updates aligned with beads molecules, agents, and gates patterns
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Beads is shelved under Build/PM because issue tracking and agent workflow context are central while implementing and coordinating work, even though the same patterns help across later phases. PM subphase fits task molecules, gates, and decision frameworks that turn specs into trackable bd work without duplicating CLI reference in the skill file.
Where it fits
Decompose an approved feature into bd issues with molecules instead of ad-hoc chat to-do lists.
Run bd prime before a release checklist so the agent sees current gate and status commands.
Triage production follow-ups by updating bd work items with hook-loaded workflow context.
How it compares
Use as the beads-specific workflow skill—not a replacement for brainstorming or writing-plans when you still need a human-approved spec first.
Common Questions / FAQ
Who is beads for?
Indie developers and agent users who track work with the bd/beads CLI and want DRY, auto-updating command context instead of static SKILL.md CLI encyclopedias.
When should I use beads?
Use it during Build (PM) while breaking down implementation, during Ship (launch) to close release tasks, and during Operate (iterate) when agents update or gate bd issues—whenever bd is the system of record.
Is beads safe to install?
It is procedural documentation for a local CLI; review the Security Audits panel on this page and treat bd commands that touch git or network like any other shell automation.
SKILL.md
READMESKILL.md - Beads
# ADR-0001: Use bd prime as CLI Reference Source of Truth ## Status Accepted ## Context The beads skill maintained CLI reference documentation in multiple locations: - `SKILL.md` inline (~2,000+ words of CLI reference) - `references/CLI_REFERENCE.md` (~2,363 words) - Scattered examples throughout resource files This created: - **Duplication**: Same commands documented 2-3 times - **Drift risk**: Documentation can fall behind bd versions - **Token overhead**: ~3,000+ tokens loaded even for simple operations Meanwhile, bd provides `bd prime` which generates AI-optimized workflow context automatically. ## Decision Use `bd prime` as the single source of truth for CLI commands: 1. **SKILL.md** contains only value-add content (decision frameworks, cognitive patterns) 2. **CLI reference** points to `bd prime` (auto-loaded by hooks) and `bd --help` 3. **Resources** provide depth for advanced features (molecules, agents, gates) ## Consequences ### Positive - **Zero maintenance**: CLI docs auto-update with bd versions - **DRY**: Single source of truth - **Accurate**: No version drift possible - **Lighter SKILL.md**: ~500 words vs ~3,300 ### Negative - **Dependency on bd prime format**: If output changes significantly, may need adaptation - **External tool requirement**: Skill assumes bd is installed ## Implementation Files restructured: - `SKILL.md` — Reduced from 3,306 to ~500 words - `references/` → `resources/` — Directory rename for consistency - New resources added: `agents.md`, `async-gates.md`, `chemistry-patterns.md`, `worktrees.md` - Existing resources preserved with path updates ## Related - Claude Code skill progressive disclosure guidelines - Similar pattern implemented in other Claude Code skill ecosystems ## Date 2025-01-02 interface: display_name: "Beads" short_description: "Project task tracking with bd" default_prompt: "Use $beads to inspect ready work and manage durable project tasks." # Beads Skill Maintenance Guide ## Architecture Decisions ADRs in `adr/` document key decisions. These are NOT loaded during skill invocation—they're reference material for maintainers making changes. | ADR | Decision | |-----|----------| | [ADR-0001](adr/0001-bd-prime-as-source-of-truth.md) | Use `bd prime` as CLI reference source of truth | ## Key Principle: DRY via bd prime **NEVER duplicate CLI documentation in SKILL.md or resources.** - `bd prime` outputs AI-optimized workflow context - `bd <command> --help` provides specific usage - Both auto-update with bd releases **SKILL.md should only contain:** - Decision frameworks (bd vs TodoWrite) - Prerequisites (install verification) - Resource index (progressive disclosure) - Pointers to `bd prime` and `--help` ## Keeping the Skill Updated ### When bd releases new version: 1. **Check for new features**: `bd --help` for new commands 2. **Update SKILL.md frontmatter**: `version: "X.Y.Z"` 3. **Add resources for conceptual features** (agents, gates, chemistry patterns) 4. **Don't add CLI reference** — that's `bd prime`'s job ### What belongs in resources: | Content Type | Belongs in Resources? | Why | |--------------|----------------------|-----| | Conceptual frameworks | ✅ Yes | bd prime doesn't explain "when to use" | | Decision trees | ✅ Yes | Cognitive guidance, not CLI reference | | Advanced patterns | ✅ Yes | Depth beyond `--help` | | CLI command syntax | ❌ No | Use `bd <cmd> --help` | | Workflow checklists | ❌ No | `bd prime` covers this | ### Resource update checklist: ``` [ ] Check if bd prime now covers this content [ ] If yes, remove from resources (avoid duplication) [ ] If no, update resource for new bd version [ ] Update version compatibility in README.md ``` ## File Roles | File | Purpose | When to Update | |------|---------|----------------| | SKILL.md | Entry point, resource index | New features, version bumps | | README.md | Human docs, installation | Structure changes | | CLAUDE.md | This file, maintenance guide | Architecture