Beads
Keep durable project tasks, blockers, and handoffs in bd/Beads instead of ad-hoc notes when shipping with agents across sessions.
Overview
Beads is an agent skill most often used in Build (also Ship, Operate) that drives the `bd` CLI so solo builders claim, track, and close durable project tasks with blockers and multi-session handoff.
Install
npx skills add https://github.com/madebymlai/agentstack --skill beadsWhat is this skill?
- Starts with `bd prime` and `bd where` to confirm an active Beads workspace
- Ready-work flow: `bd ready`, `bd list --status=open|in_progress`, then `bd show <id>` before edits
- Atomic claim via `bd update <id> --claim` and close with `bd close` patterns
- Creates follow-up tasks with `bd create` including title, description, type, and priority
- Treats Beads as durable source of truth over local plans and scratch files
- 5-step core CLI workflow from inspect through close
Adoption & trust: 1 installs on skills.sh; trending (+100% hot-view momentum).
What problem does it solve?
You lose project context between agent sessions because tasks live in chat, scratch files, or local plans instead of a shared dependency-aware queue.
Who is it for?
Repos already wired to Beads/bd where you want agents to discover ready work, respect blockers, and maintain a single task source of truth.
Skip if: Greenfield projects without a Beads workspace or when you only need a one-off checklist with no cross-session tracking.
When should I use this skill?
User asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent Beads tracking in a bd-enabled repo.
What do I get? / Deliverables
After running Beads workflows, ready work is visible, tasks are claimed and closed in `bd`, and follow-up issues are recorded as durable graph nodes for the next session.
- Updated task states (claimed, in progress, closed) in Beads
- New follow-up issues created via `bd create` when work expands
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because bd is where implementation work is claimed, tracked, and closed against the repo’s shared task graph. PM subphase fits issue tracking, dependencies, ready-work queues, and multi-session continuity—the core beads workflow.
Where it fits
Run `bd ready` and claim the next integration task before the agent edits code.
Close completed launch checklist items and create follow-up tasks for release blockers.
Inspect open blockers and recover project context after a week away from the repo.
How it compares
Persistent issue graph with CLI semantics, not a generic markdown todo list in the repo root.
Common Questions / FAQ
Who is beads for?
Solo and indie builders (and small teams) using Claude Code, Cursor, or Codex in repositories that already use Beads or `bd` for project memory.
When should I use beads?
During Build when claiming implementation tasks; in Ship when closing launch prep items and filing regressions; in Operate when triaging blockers and recovering context after idle time—whenever the user asks for ready work, claims, or durable follow-ups.
Is beads safe to install?
Review the Security Audits panel on this Prism page and limit shell access to trusted repos; the skill expects `bd` commands that modify task state in your workspace.
SKILL.md
READMESKILL.md - Beads
interface: display_name: "Beads" short_description: "Project task tracking with bd" default_prompt: "Use $beads to inspect ready work and manage durable project tasks." --- name: beads description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking. --- # Beads Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work. ## First Step Run: ```bash bd prime ``` If that prints nothing, check whether the repository has an active Beads workspace: ```bash bd where ``` ## Preferred Route Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface. ## Core CLI Workflow 1. Find work: ```bash bd ready bd list --status=open bd list --status=in_progress ``` 2. Inspect before editing: ```bash bd show <id> ``` 3. Claim work atomically: ```bash bd update <id> --claim ``` 4. Create durable follow-up work when implementation reveals new tasks: ```bash bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2 ``` 5. Close completed work: ```bash bd close <id> --reason="Completed" ``` ## What Belongs In Beads Use Beads for: - shared project tasks - blockers and dependencies - discovered follow-up work - work that must survive thread reset, compaction, or handoff - status that another person or agent should be able to resume Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state. ## Rules - Do not create markdown TODO files as the source of truth when Beads is available. - Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead. - Prefer `--json` when parsing `bd` output programmatically. - If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing. - Do not auto-close or mutate tasks unless the work is actually complete.