Beads Issue Tracking Skill
> **Attribution**: [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge)
About this skill
The Beads Issue Tracking Skill empowers AI agents to seamlessly interact with Beads, a sophisticated git-backed issue tracking system developed by Steve Yegge. This skill provides a structured framework for agents to perform various issue management operations directly within their development environment. It facilitates an AI-native approach to task management, ensuring that agents can effectively contribute to and manage projects by leveraging Beads' unique capabilities. Agents can utilize this skill for a wide range of activities, including initiating work sessions, creating new issues with specific types and priorities, and attaching relevant files for context. It also supports advanced features like managing task dependencies, executing predefined workflow formulas, and coordinating work across multiple agent sessions. The skill's integration with git ensures that all issue data is version-controlled and easily accessible. By adopting the Beads Issue Tracking Skill, AI agents can maintain organized project states, track progress efficiently, and automate routine issue management tasks. This leads to a more coherent and productive development workflow, allowing agents to focus on code implementation while Beads handles the overhead of issue tracking and coordination.
Best use case
The primary use case for this skill is enabling AI agents to autonomously manage and track development-related tasks and issues directly within a Git-versioned project. AI agents tasked with coding, bug fixing, documentation, or feature implementation benefit most, as they can independently update their work status, create follow-up tasks, and adhere to project workflows without manual intervention, thereby streamlining the entire development lifecycle.
> **Attribution**: [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge)
A project's issues, tasks, and workflows are effectively managed and tracked within a Git repository by an AI agent, ensuring transparent progress and structured development.
Practical example
Example input
As an AI agent, I need to create a new feature for 'User Profile Management' with high priority. Please use the Beads skill to create this issue.
Example output
Issue created: FEATURE-123 'User Profile Management' (Priority: High). Run `bd prime` to begin work or `bd ready` to find available tasks.
When to use this skill
- Starting a new work session (bd prime → bd ready)
- Creating, updating, or closing issues
- Managing task dependencies
- Running workflow formulas
When not to use this skill
- When the project does not use Git for version control.
- When a team already has a deeply integrated, non-Beads issue tracking system.
- For purely project management tasks that don't involve code or technical development.
- If the agent lacks the necessary shell access or execution privileges to run `bd` commands.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/beads/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How Beads Issue Tracking Skill Compares
| Feature / Agent | Beads Issue Tracking Skill | Standard Approach |
|---|---|---|
| Platform Support | Claude | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | medium | N/A |
Frequently Asked Questions
What does this skill do?
> **Attribution**: [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge)
Which AI agents support this skill?
This skill is designed for Claude.
How difficult is it to install?
The installation complexity is rated as medium. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Beads Issue Tracking Skill > **Attribution**: [Beads](https://github.com/steveyegge/beads) by [Steve Yegge](https://github.com/steveyegge) ## Description Beads is a git-backed, AI-native issue tracking system. This skill helps AI agents work with Beads effectively. ## When to Use - Starting a new work session (bd prime → bd ready) - Creating, updating, or closing issues - Managing task dependencies - Running workflow formulas - Coordinating multi-session work ## Quick Reference ### Session Workflow ```bash # START bd prime # Inject context bd ready # Find available work # WORK bd update ID --status in_progress # Take task # ... implement ... bd close ID --reason "Done" # Complete task /push patch # Commit # END (MANDATORY!) bd sync git push ``` ### Issue Creation ```bash # Basic bd create "Title" -t type -p priority # With files (auto-labels) bd create "Fix button" --files src/components/Button.tsx # Emergent work bd create "Found bug" -t bug --deps discovered-from:current-id ``` ### Types & Priorities | Type | When | |------|------| | feature | New functionality | | bug | Bug fix | | chore | Tech debt, config | | docs | Documentation | | test | Tests | | epic | Group of tasks | | Priority | Meaning | |----------|---------| | 0 | Critical (blocks release) | | 1 | Critical | | 2 | High | | 3 | Medium (default) | | 4 | Low / backlog | ### Formulas (Workflows) ```bash bd formula list # List all bd mol wisp exploration --vars "question=How?" # Ephemeral bd mol pour bigfeature --vars "feature_name=auth" # Persistent bd mol squash WISP_ID # Save result bd mol burn WISP_ID # Discard ``` ## Resources See `resources/` for detailed guides: - COMMANDS_QUICKREF.md - Command cheat sheet - DECISION_MATRIX.md - When to use what - WORKFLOWS.md - Common workflows - SPECKIT_BRIDGE.md - Integration with Spec-kit ## Integration with Spec-kit For large features (>1 day): 1. `/speckit.specify` → requirements 2. `/speckit.plan` → design 3. `/speckit.tasks` → task breakdown 4. `/speckit.tobeads` → import to Beads 5. `bd ready` → work with Beads ## Links - [Beads GitHub](https://github.com/steveyegge/beads) - [CLI Reference](https://github.com/steveyegge/beads/blob/main/docs/CLI_REFERENCE.md)
Related Skills
ai-pair
AI Pair Collaboration Skill. Coordinate multiple AI models to work together: one creates (Author/Developer), two others review (Codex + Gemini). Works for code, articles, video scripts, and any creative task. Trigger: /ai-pair, ai pair, dev-team, content-team, team-stop
review
Daily and weekly review workflows. USE WHEN user says "morning routine", "evening routine", "weekly review", "start my day", "end of day".
prd
Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out.
Skill: Runs
## Purpose
Claude-Zeroclaw SKILL
## Overview
reprompter
Transform messy prompts into structured, effective prompts — single, multi-agent, or reverse-engineered from great outputs. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags, "reprompter teams", "repromptverse", "run with quality", "smart run", "smart agents", "campaign swarm", "engineering swarm", "ops swarm", "research swarm", multi-agent tasks, audits, parallel work, "reverse reprompt", "reprompt from example", "learn from this", "extract prompt from", "prompt dna", "prompt genome", reverse-engineering prompts from exemplar outputs. Don't use for simple Q&A, pure chat, or immediate execution-only tasks (see "Don't Use When" section). Outputs: structured XML/Markdown prompt, before/after quality score, optional team brief + per-agent sub-prompts, Agent Cards, Extraction Card (reverse mode). Target quality score: Single ≥ 7/10; Repromptverse per-agent ≥ 8/10; Reverse ≥ 7/10.
session-pack
세션 종료 시 Memory, Handoff를 자동 정리. /pack
execute
Main entry point for hierarchical task execution. Orchestrates layer-by-layer implementation of PRD tasks with parallel worktree execution.
textum
Textum PRD→Scaffold→Story workflow for Codex with low-noise outputs and gate checks.
sdd
This skill should be used when users want guidance on Spec-Driven Development methodology using GitHub's Spec-Kit. Guide users through executable specification workflows for both new projects (greenfield) and existing codebases (brownfield). After any SDD command generates artifacts, automatically provide structured 10-point summaries with feature status tracking, enabling natural language feature management and keeping users engaged throughout the process.
nonstop
Enables an autonomous work mode for AI agents, allowing continuous operation without user interruption. It includes a pre-flight risk assessment and intelligent blocker handling to maximize productivity.
superbuild
Use when executing implementation plans phase-by-phase with strict enforcement of quality gates, tests, and Definition of Done. Triggers on "build this plan", "execute plan", "implement phases", or when user provides a plan document to execute.