Name: beads
Author: block

About

Imported from block/agent-skills (beads/SKILL.md). Install upstream with npx skills add block/agent-skills --skill beads. Copyright stays with the author.

This skill teaches effective use of beads (bd), a distributed git-backed issue tracker designed for AI agents. Use beads to track tasks, manage dependencies, and coordinate work across sessions.

Getting Started

First, check if beads is available and initialized:

# Check if bd is installed
bd version

# Check if current project has beads initialized
bd status

If bd is not installed, ask the user which installation method they prefer:

npm: npm install -g @beads/bd
Homebrew: brew install beads (macOS)
Go: go install github.com/steveyegge/beads/cmd/bd@latest

Do not install without user confirmation, as these are global system packages.

If not initialized in the project, run:

bd init

For personal use on shared projects (won't commit to repo):

bd init --stealth

For contributors on forked repos (routes to separate planning repo):

bd init --contributor

Essential Commands

Command	Purpose
`bd ready`	List tasks with no open blockers (what to work on next)
`bd create "Title" -p 1`	Create a task (priority 0-3, lower = higher priority)
`bd show <id>`	View task details and dependencies
`bd list`	List all open issues
`bd close <id>`	Mark task as complete
`bd update <id> --status in_progress`	Update task status
`bd dep add <child> <parent>`	Create dependency (child blocked by parent)
`bd sync`	Force immediate sync to git

Always use --json flag for machine-readable output when parsing results.

Task Hierarchy

Beads supports hierarchical IDs for organizing work:

bd-a3f8 — Epic (large feature)
bd-a3f8.1 — Task under epic
bd-a3f8.1.1 — Sub-task

Create hierarchical tasks:

bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8

Session Workflow

Starting a Session

# See what's ready to work on
bd ready --json

# Pick a task and mark it in progress
bd update <id> --status in_progress

# View full details
bd show <id> --json

During Work

# Create new tasks as you discover them
bd create "Fix edge case in validation" -p 2

# Add dependencies
bd dep add <new-task> <blocking-task>

# Update task with notes
bd update <id> --notes "Found issue with timezone handling"

Ending a Session ("Land the Plane")

When finishing work, complete ALL these steps:

# 1. File issues for remaining work
bd create "TODO: Add integration tests" -p 2

# 2. Close completed tasks
bd close <id> --reason "Completed"

# 3. Sync and push (MANDATORY)
git pull --rebase
bd sync
git push

# 4. Verify push succeeded
git status  # Must show "up to date with origin"

# 5. Identify next task for follow-up
bd ready --json

CRITICAL: Always push before ending a session. Unpushed work causes coordination problems in multi-agent workflows.

Important Rules

DO use `bd update` with flags

bd update <id> --description "new description"
bd update <id> --title "new title"  
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
bd update <id> --status in_progress

DO NOT use `bd edit`

The edit command opens an interactive editor ($EDITOR) which AI agents cannot use. Always use bd update with flags instead.

DO sync before ending sessions

bd sync  # Forces immediate export, commit, and push

Without bd sync, changes sit in a 30-second debounce window and may not be committed.

DO include issue IDs in commit messages

git commit -m "Fix auth validation bug (bd-abc)"

This enables bd doctor to detect orphaned issues.

Dependency Types

# Hard blocker - child cannot start until parent is done
bd dep add <child> <parent> --type blocks

# Soft link - related but not blocking  
bd dep add <issue1> <issue2> --type related

# Parent-child - hierarchical relationship
bd dep add <child> <parent> --type parent-child

Handling Merge Conflicts

If conflicts occur in .beads/issues.jsonl:

# Accept remote version
git checkout --theirs .beads/issues.jsonl

# Re-import to database
bd import -i .beads/issues.jsonl

# Continue with your work

Git Hooks (Recommended)

Install hooks for automatic sync:

bd hooks install

This prevents stale JSONL problems by auto-syncing on commit, merge, push, and checkout.

MCP Server Alternative

For tighter integration, beads also offers an MCP server (beads-mcp) that provides tools directly to your agent. Install via:

pip install beads-mcp

The CLI (bd) and MCP server work with the same underlying database.

Quick Reference

# What should I work on?
bd ready

# Create a task
bd create "Fix bug in login" -p 1

# Start working
bd update bd-xyz --status in_progress

# Done working
bd close bd-xyz --reason "Completed"
bd sync
git push

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/block-agent-skills-beads/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

block-agent-skills-beads.ocm.jsonjson

{
  "ocm": "1",
  "id": "block-agent-skills-beads",
  "kind": "skill",
  "name": "beads",
  "description": "Use beads (bd) for persistent task tracking in coding projects. A git-backed issue tracker designed for AI agents with dependency graphs, hierarchical tasks, and multi-agent coordination.",
  "publisher": "block",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "development",
      "productivity",
      "task-management",
      "workflow",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Use beads (bd) for persistent task tracking in coding projects. A git-backed issue tracker designed for AI agents with dependency graphs, hierarchical tasks, and multi-agent coordination."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/block/agent-skills",
      "path": "beads/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/block/agent-skills/blob/HEAD/beads/SKILL.md",
      "key": "block/agent-skills/beads/SKILL.md"
    }
  },
  "instructions": "This skill teaches effective use of **beads** (`bd`), a distributed git-backed issue tracker designed for AI agents. Use beads to track tasks, manage dependencies, and coordinate work across sessions.\n\n## Getting Started\n\nFirst, check if beads is available and initialized:\n\n```bash\n# Check if bd is installed\nbd version\n\n# Check if current project has beads initialized\nbd status\n```\n\n**If `bd` is not installed**, ask the user which installation method they prefer:\n- **npm:** `npm install -g @beads/bd`\n- **Homebrew:** `brew install beads` (macOS)\n- **Go:** `go install github.com/steveyegge/beads",
  "cost": {
    "context_tokens": 1251
  }
}

Fetch it by URL: GET /api/v1/registry/block-agent-skills-beads/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.