beads/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)
├── README.md                # This file (for humans)
└── references/              # Detailed documentation (loaded on demand)
    ├── BOUNDARIES.md        # When to use bd vs TodoWrite
    ├── CLI_BOOTSTRAP_ADMIN.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

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

• v0.34.0+: Full support including molecules, wisps, and cross-project dependencies
• v0.15.0+: Core functionality (dependencies, notes, status tracking)
• Earlier versions: Basic functionality but some features may be missing

Contributing

This skill is maintained at github.com/steveyegge/beads in the 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)