Beads Project Tracker

Name: Beads Project Tracker
Author: gastownhall

By gastownhall· gastownhall/beads· 0

Manage durable task tracking, dependencies, and blockers for shared project work.

Installation

1
Make sure Claude is on your device and in your terminal.
Skills load from ~/.claude/skills/ when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then run claude in any terminal to verify.
One-time setup
```
npm i -g @anthropic-ai/claude-code
```
Already have it? Skip ahead.

Paste into Claude Code or into your terminal.

Install

git clone ht•••••••••••••••••••••••••••••••••••••• ••••••••••••••••••••••• •• ••••• •• •••••••••••••••••••••••••••••••••• •• •• •• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •••••••••••••••••••••••••••••••••••

This copies the whole skill folder into ~/.claude/skills/beads-gastownhall/ — the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Safe default: works for every skill.

Faster alternative (instruction-only skills)

Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.

Quick install (SKILL.md only)

mkdir -p ~/.••••••••••••••••••••••••••••••• •• •••• ••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •• •••••••••••••••••••••••••••••••••••••••••••

Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from ~/.claude/skills/). New skills are picked up on startup.
Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.

Prefer to read the source first? Open on GitHub.

When Claude uses it

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.

What this skill does

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:

bd prime

If that prints nothing, check whether the repository has an active Beads workspace:

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

Find work:

bd ready
bd list --status=open
bd list --status=in_progress

Inspect before editing:

bd show <id>

Claim work atomically:

bd update <id> --claim

Create durable follow-up work when implementation reveals new tasks:

bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2

Close completed work:

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.

Related skills

App Store Listing Audit

coreyhaines31

Analyze your app listing against best practices and get a prioritized optimization plan.

Co-Marketing Partnerships

coreyhaines31

Find ideal partners and plan joint marketing campaigns with other companies.

Cold Email Writer

coreyhaines31

Write B2B cold emails and follow-up sequences designed to get replies.

Community-Led Growth

coreyhaines31

Build and grow online communities to drive product adoption and customer loyalty.