Claude-skill-registry 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".

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/beads-cli" ~/.claude/skills/majiayu000-claude-skill-registry-beads-cli && rm -rf "$T"

manifest: 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

# 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

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

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

Claiming Protocol (Multi-Agent)

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

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.

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

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

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