skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
oakoss/agent-skills88 installs

beads-workflow

Converts markdown plans into beads (tasks with dependencies) and polishes them until implementation-ready. The bridge between planning and agent swarm execution. Use when converting a plan to beads, polishing bead descriptions, adding test coverage beads, reviewing bead dependencies, or preparing tasks for agent swarm execution.

How do I install this agent skill?

npx skills add https://github.com/oakoss/agent-skills --skill beads-workflow
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is functional for task management but introduces a potential surface for indirect prompt injection by processing external markdown files without explicit boundary markers or sanitization.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerwarn

    4/4 files flagged

What does this agent skill do?

Beads Workflow

Beads are epics, tasks, and subtasks with dependency structure, optimized for AI coding agents. They function like Jira or Linear but designed for machines. This skill covers the full lifecycle: converting markdown plans into beads, iteratively polishing them across multiple rounds and models, and integrating with the bd CLI and Agent Mail for swarm execution. Use this when you have a markdown plan and need to produce self-contained, implementation-ready tasks. Do not use this for the planning phase itself; use a planning skill for that.

Core Principle: "Check your beads N times, implement once" -- where N is as many as you can stomach.

Quick Reference

WorkflowWhat It DoesKey Detail
Plan to beadsConverts a markdown plan into granular beads with dependenciesUse the full or short conversion prompt with bd tool
Polish beadsIteratively reviews and improves bead qualityRun 6-9 rounds until steady-state; use full or standard prompt
Fresh sessionBreaks out of polishing plateausStart new session, re-establish context, then resume polishing
Cross-model reviewGets alternative perspectives on bead qualityRun final pass with a different model (Codex, Gemini CLI)
Add test coverageCreates unit test and e2e test beadsUse the test coverage prompt to audit and fill gaps
bd CLI basicsCreate, update, depend, close beadsAlways use bd tool; never run bare bv (interactive TUI)
Robot modeMachine-readable bv output for agentsbv --robot-triage, --robot-next, --robot-plan, --robot-insights
Agent Mail integrationCoordinate multi-agent bead executionUse bead ID as thread_id; prefix subjects with [bd-XXX]

Common Mistakes

MistakeCorrect Pattern
Oversimplifying bead descriptions to short bullet pointsBeads must be verbose and self-documenting with background, reasoning, and considerations
Stopping after one polish roundKeep polishing until steady-state (typically 6-9 rounds); start a fresh session if progress flatlines
Omitting test coverage beadsEvery feature bead should have associated unit test and e2e test beads with detailed logging
Not making all blocking relationships explicitUse bd depend to declare every dependency; agents cannot infer implicit ordering
Losing features from the original planCross-check every plan section against beads; everything must be embedded so the plan is never consulted again
Running bare bv without flagsAlways use bv --robot-* flags; bare bv launches an interactive TUI that blocks agents

Delegation

  • Create initial beads from a markdown plan: Use Task agent with the plan-to-beads prompt and bd tool access
  • Polish beads across multiple rounds: Use Task agent with the standard polish prompt, repeating until steady-state
  • Review bead graph for cycles and missing dependencies: Use Explore agent to run bv --robot-insights and validate the dependency structure
  • Add test coverage beads: Use Task agent with the test coverage prompt

References

  • Plan to Beads -- Converting markdown plans into beads, exact prompts, what gets created
  • Polishing Workflow -- Polishing protocol, fresh session technique, cross-model review, quality checklist
  • Agent Integration -- bd CLI commands, robot mode, Agent Mail integration, test coverage beads

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/oakoss/agent-skills/beads-workflow">View beads-workflow on skillZs</a>