beads-rs: Skill for Claude Code

Atomic Bead Filing

Overview

File beads that future agents can execute with zero shared context. You receive an observation, ground it in the codebase, and create a bead that stands alone.

When to Use

• Main agent noticed something off while working
• Need to capture it without derailing current task
• Want a proper bead, not a vague note

Core Principle

A bead is good if a stranger-agent can execute it knowing ONLY:

1. The bead's description
2. The codebase (via search/read)

They should NOT need: conversation history, the observer's context, or clarification.

Workflow

1. Receive observation from main agent (you have conversation context)
2. Explore codebase to ground it - find specific files, line numbers, patterns
3. Ask questions via AskUserQuestion if genuinely unclear
4. Determine actionability:
   • Clear path → actionable bead
   • Multiple valid approaches → add human-needed label, describe options
5. File bead with bd create
6. Sync with bd sync (just git commit isn't enough - beads live on beads-sync branch)
7. Return bead ID + full bead details so main agent sees what was filed

Bead Structure

Title: Concise, grounded summary (not vague)

• Bad: "Fix type issues"
• Good: "RuleViolation missing priority field - Rust hardcodes HIGH"

Description: The concrete issue

## What's Wrong
[Specific problem - what IS off, grounded in files]

## Where
[Exact file paths, line numbers]

## Why It Matters
[What could go wrong, why this is tech debt]

## Files to Study
- path/to/file.rs (the problematic code)
- path/to/related.py (the other side of the mismatch)

Fields to set (run bd create --help to see all available):

Flag	When to use
--type task	Default. Use bug if actively broken, feature for new capability
--priority	P0 critical (security/data loss), P1 high (bugs/blockers), P2 medium, P3 low (polish), P4 backlog - default to your judgment based on impact
--labels human-needed	Multiple valid approaches exist (see below)
--deps discovered-from:<id>	Main agent was working on a specific bead
--acceptance	Fill if obvious - what would "done" look like?
--design	Fill if obvious - brief notes on approach/constraints