Agent skill

beads-cli

Task tracking with the bd (Beads) CLI. Use when creating tasks, claiming work, closing beads, managing dependencies, or when the user mentions "beads", "bd", or "tasks".

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/beads-cli

SKILL.md

Beads CLI (bd)

Task tracking across sessions. All issue tracking goes through bd.

When This Applies

Signal Action
Need to create a task bd create
Looking for work bd ready --json
Claiming a task bd update --status in_progress
Finishing a task bd close
Managing dependencies bd dep add/tree

Core Workflow

bash
# Finding work
bd ready --json                    # Unblocked tasks ready for work
bd blocked                         # Tasks waiting on dependencies
bd list                            # All tasks

# Task lifecycle
bd create "Title" -t bug -p 1      # Create with type, priority
bd update bd-42 --status in_progress --assignee YOUR_NAME  # Claim
bd close bd-42 --reason "Completed: summary"               # Complete

# Viewing
bd show bd-42                      # Full task details
bd info                            # Project summary

Dependencies

bash
bd dep add bd-child bd-blocker --type blocks        # Child blocked by blocker
bd dep add bd-a bd-b --type related                 # Related tasks
bd dep add bd-child bd-parent --type parent-child   # Hierarchy
bd dep add bd-new bd-old --type discovered-from     # Found during work
bd dep tree bd-42                                   # Visualize dependencies
bd dep cycles                                       # Find circular deps

Task Types and Priority

Type Use For
bug Defects, errors
feature New functionality
task General work items
epic Parent/container beads
chore Maintenance, cleanup
Priority Meaning
0 Critical (do first)
1 High
2 Normal
3 Low
4 Backlog

Child Beads

Hierarchical IDs: bd-a1b2.1, bd-a1b2.3.1

bash
bd create "Sub-task" --parent bd-123 -p 1

Claiming Protocol (Multi-Agent)

CRITICAL: Always claim parent AND all sub-beads together.

bash
bd update bd-123 --status in_progress --assignee YOUR_NAME
bd update bd-123.1 --status in_progress --assignee YOUR_NAME
bd update bd-123.2 --status in_progress --assignee YOUR_NAME

Why: If you only claim parent, other agents see sub-beads as "ready" → CONFLICT.

Closing Protocol

CRITICAL: Close sub-beads first, then parent.

bash
bd close bd-123.1 --reason "Completed: implemented X"
bd close bd-123.2 --reason "Completed: added tests"
bd close bd-123 --reason "Completed: full feature done"

Maintenance

bash
bd doctor                          # Health check
bd doctor --fix                    # Auto-fix issues
bd compact --analyze --json        # Analyze for compaction
bd --readonly list                 # Safe read-only mode

Key Rules

Rule Why
Always commit .beads/ with code Keeps state in sync
Never edit .beads/*.jsonl directly Use bd commands only
Always set --assignee when claiming Prevents conflicts
Never use other TODO systems Beads is authoritative

Quick Reference

bash
bd ready --json          # What's available?
bd update ID --status in_progress --assignee NAME   # Claim
bd close ID --reason "..."   # Complete
bd create "Title" -t TYPE -p PRIORITY   # Create
bd dep add CHILD BLOCKER --type blocks   # Add dependency
bd doctor --fix          # Health check

See Also

  • beads-viewer/ — Graph analysis with bv
  • advance/ — Full bead lifecycle (claiming, working, closing)

Didn't find tool you were looking for?

Be as detailed as possible for better results