beads/claude-plugin/skills/beads

Beads Skill for Claude Code

A comprehensive skill for using beads (bd) issue tracking with Claude Code.

What This Skill Does

This skill teaches Claude Code how to use bd effectively for:

• Multi-session work tracking - Persistent memory across conversation compactions
• Dependency management - Graph-based issue relationships
• Session handoff - Writing notes that survive context resets
• Molecules and wisps (v0.34.0+) - Reusable work templates and ephemeral workflows

Installation

Copy the beads/ directory to your Claude Code skills location:

# Global installation
cp -r beads ~/.claude/skills/

# Or project-local
cp -r beads .claude/skills/

When Claude Uses This Skill

The skill activates when conversations involve:

• "multi-session", "complex dependencies", "resume after weeks"
• "project memory", "persistent context", "side quest tracking"
• Work that spans multiple days or compaction cycles
• Tasks too complex for simple TodoWrite lists

File Structure

beads/
├── SKILL.md                 # Main skill file (Claude reads this first)
├── CLAUDE.md                # Maintenance guide for updating the skill
├── README.md                # This file (for humans)
├── adr/                     # Architectural Decision Records
│   └── 0001-bd-prime-as-source-of-truth.md
└── resources/               # Detailed documentation (loaded on demand)
    ├── BOUNDARIES.md        # When to use bd vs TodoWrite
    ├── CLI_REFERENCE.md     # CLI command reference
    ├── DEPENDENCIES.md      # Dependency semantics (A blocks B vs B blocks A)
    ├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration
    ├── ISSUE_CREATION.md    # When and how to create issues
    ├── MOLECULES.md         # Protos, mols, wisps (v0.34.0+)
    ├── PATTERNS.md          # Common usage patterns
    ├── RESUMABILITY.md      # Writing notes for post-compaction recovery
    ├── STATIC_DATA.md       # Using bd for reference databases
    ├── TROUBLESHOOTING.md   # Common issues and fixes
    ├── WORKFLOWS.md         # Step-by-step workflow guides
    ├── AGENTS.md            # Agent bead tracking (v0.40+)
    ├── ASYNC_GATES.md       # Human-in-the-loop gates
    ├── CHEMISTRY_PATTERNS.md # Mol vs Wisp decision tree
    └── WORKTREES.md         # Parallel development patterns

Key Concepts

bd vs TodoWrite

Use bd when...	Use TodoWrite when...
Work spans multiple sessions	Single-session tasks
Complex dependencies exist	Linear step-by-step work
Need to resume after weeks	Just need a quick checklist
Knowledge work with fuzzy boundaries	Clear, immediate tasks

The Dependency Direction Trap

bd dep add A B means "A depends on B" (B must complete before A can start).

# Want: "Setup must complete before Implementation"
bd dep add implementation setup  # ✓ CORRECT
# NOT: bd dep add setup implementation  # ✗ WRONG

Surviving Compaction

When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context:

bd update issue-123 --notes "COMPLETED: JWT auth with RS256
KEY DECISION: RS256 over HS256 for key rotation
IN PROGRESS: Password reset flow
NEXT: Implement rate limiting"

Requirements

• bd CLI installed (brew install steveyegge/beads/bd)
• A git repository (bd requires git for sync)
• Initialized database (bd init in project root)

Version Compatibility

Version	Features
v0.47.0+	Pull-first sync, resolve-conflicts, dry-run create, gate auto-discovery
v0.43.0+	Full support: agents, gates, worktrees, chemistry patterns
v0.40.0+	Agent beads, async gates, worktree management
v0.34.0+	Molecules, wisps, cross-project dependencies
v0.15.0+	Core: dependencies, notes, status tracking
Earlier	Basic functionality, some features missing

Contributing

This skill is maintained at github.com/steveyegge/beads in the claude-plugin/skills/beads/ directory.

Issues and PRs welcome for:

• Documentation improvements
• New workflow patterns
• Bug fixes in examples
• Additional troubleshooting scenarios

License

MIT (same as beads)