Agent skill

bead-creator

Create self-contained Beads issues for work tracking. Use when creating new beads for bugs, tasks, questions, or follow-up work - whether from specifications, discovered during implementation, or standalone requests. Handles proper formatting, labeling, dependencies, and ensures beads are actionable with embedded context.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/moogah/claude_skills/tree/main/bead-creator

SKILL.md

Bead Creator

Create self-contained, actionable Beads issues with proper context and structure.

Core Principle

Beads must be self-contained. Each bead description must contain all context needed for implementation without referencing external documents.

Creating Simple Beads

For straightforward tasks, use the basic pattern:

bash
bd create "Add TypeScript strict mode to stack config" \
  -t task -p 2 -l typescript,infrastructure

bd update beads-xxx --description "Enable TypeScript strict mode for oncall-background-processes-stack.

Files to modify:
- stacks/oncall-background-processes-stack/tsconfig.json

Changes:
1. Add 'strict: true' to compilerOptions
2. Add 'strictNullChecks: true' (redundant but explicit)
3. Ensure 'noImplicitAny: true' is present

Design rationale: Strict mode catches type errors early and improves code quality. This stack uses CDK infrastructure code where type safety is critical for preventing runtime deployment errors.

Verification:
- Run bash scripts/type-check.sh
- Confirm no new type errors introduced"

Creating Follow-Up Beads During Implementation

When discovering work during implementation, externalize it immediately:

Bug Discovered

bash
bd create "Fix null check in assignment-day-utils.js" \
  -t bug -p 1 -l bugfix,follow-up \
  --deps "discovered-from:beads-abc" \
  --description "While implementing dual-write, discovered missing null check in assignment-day-utils.js line 47. The getCompanyId() function doesn't handle undefined assignmentDay input, causing crashes in edge cases.

Files to modify:
- utils/assignment-day-utils.js

Fix:
Add null check before accessing assignmentDay.companyId

Context: Discovered during beads-abc implementation when testing edge cases"

Unclear Requirement

bash
bd create "Clarify error handling strategy for Apollo failures" \
  -t task -p 2 -l question,follow-up \
  --deps "discovered-from:beads-abc" \
  --description "During implementation, uncertain about: should Apollo failures in dual-write mode fail the entire operation or just log warnings? Need product/architecture decision.

Context: Working on ShiftUpdate dual-write implementation. AppSync failures currently fail the operation, but unclear if Apollo should behave the same way."

Related Work Discovered

bash
bd create "Apply dual-write pattern to 3 other Lambdas" \
  -t task -p 2 -l migration,follow-up \
  --deps "discovered-from:beads-abc" \
  --description "Same dual-write pattern needed for:
- NotifyOnShiftCancel (similar event trigger)
- CalculateCoveredShift (similar data flow)
- CreateUnassigned (similar mutation pattern)

Use ShiftUpdateIntegration as reference implementation.

Implementation: Follow the established pattern from beads-abc"

Bead Description Template

Every bead description should follow this structure:

[One-line summary of what this accomplishes]

Files to modify:
- path/to/file1.ext
- path/to/file2.ext

Implementation steps:
1. Specific actionable step with details
2. Another step, include code patterns if relevant
3. Be concrete - mention functions, variables, patterns

Design rationale: [WHY - the reasoning behind this]
[Architectural context explaining this implementation]
[Technology choices, patterns, tradeoffs]

Design pattern: [Pattern to follow if applicable]
[Reference similar code if relevant]

Verification:
- How to test this works
- Acceptance criteria
- What "done" looks like

Label Conventions

Use consistent labeling for easy querying:

bash
# Project/feature labels
-l migration,lambda,apollo

# Type labels
-l bugfix,follow-up,question,blocker

# Querying by label
bd list --label migration
bd ready --label apollo

Dependency Patterns

Add dependencies when tasks must be sequenced:

bash
# Task Y depends on X completing first
bd dep add beads-yyy beads-xxx

# Track discovery without blocking
--deps "discovered-from:beads-xxx"

# Multiple dependencies
--deps "discovered-from:beads-abc,blocks:beads-xyz"

Common dependency patterns:

  • Infrastructure before application code
  • Data migrations before feature rollout
  • Shared utilities before dependent features

Best Practices

Self-contained context:

  • Extract and embed all necessary information in the description
  • Don't reference external documents - copy the relevant context
  • Include WHY (rationale) not just WHAT (steps)

Actionable steps:

  • Specific file paths
  • Concrete code patterns
  • Clear verification criteria

Appropriate granularity:

  • Target 1-4 hours per bead (one focused session)
  • Split larger work into multiple beads
  • Combine tiny tasks together

Proper classification:

  • Type: task (feature work), bug (fixes), question (needs clarification)
  • Priority: 1 (urgent), 2 (normal), 3 (low)
  • Labels: project names, feature areas, task types

Track relationships:

  • Use discovered-from for follow-up work
  • Use blocks for hard dependencies
  • Use consistent labels for related work

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

moogah/claude_skills

characterization-testing

Guide for characterization testing - capturing current system behavior to enable safe refactoring. Use when working with legacy code, undocumented systems, or code that needs modification but lacks tests. Helps create a safety net before making changes by testing what the code actually does (not what it should do).

0 0
Explore
moogah/claude_skills

bead-implementation

Execute on a Beads issue with proper discovery workflow and mandatory session close protocol. Use when starting work on a bead, during implementation when discovering new work that should be externalized, or when completing a session to ensure all work is properly committed.

0 0
Explore
moogah/claude_skills

architecture-analyzer

Perform in-depth architectural analysis of codebases through iterative dialog and visual diagrams. Use when users want to understand their software architecture, explore design patterns and anti-patterns, evaluate potential architectural changes, or gain deep insights into code structure and relationships. Particularly valuable for onboarding to unfamiliar codebases, assessing technical debt, planning refactoring efforts, or understanding how components interact across system boundaries.

0 0
Explore
moogah/claude_skills

openspec-to-beads

Convert OpenSpec artifacts (proposal.md, design.md, tasks.md, specs/) into self-contained Beads issues for implementation tracking. Use when you have completed OpenSpec planning artifacts and need to create trackable implementation tasks, or when converting any specification or design document into actionable Beads issues.

0 0
Explore
moogah/claude_skills

github-actions-troubleshooting

Troubleshoot and fix failing GitHub Actions pipeline steps. Use when user reports a failing pipeline with error output.

0 0
Explore
moogah/claude_skills

skill-learner

Reviews conversation context to identify learnings and patterns that should be captured in skills. Use when the user asks to review the session for skill creation or updates.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results