What Is Bead Engineering? A Practical Guide

A few months back I rewrote the same forty line system prompt for the third time in a week, hunting for which paragraph was making Claude ignore my output format. That's when I stopped writing prompts as paragraphs and started building them out of beads.

TL;DR

• A bead is one job, not a paragraph. Persona, task, constraint, and output format each get their own bead.
• Debug one bead at a time. When output breaks, you know exactly which piece to fix instead of rewriting the whole prompt.
• Build a reusable bead library instead of one off prompts you rewrite from scratch every time.
• Load beads progressively. Put what every session needs up front, push what's rarely needed into a reference file.
• Compose beads with code when the shape of the prompt changes based on input, not by hand every time.
• Beads fix structure, loops fix repetition. Most real agent work needs both, not one instead of the other.

A bead is one job, not a paragraph

There's no official definition of "bead" the way there is for chain of thought or few shot prompting. It's a name a lot of practitioners have landed on for something the research world calls modular prompting: breaking a task into small, single purpose pieces instead of one long block of text trying to do everything at once.

A typical set of beads looks like this:

• Persona bead: "You are a blunt code reviewer who has shipped production Python for a decade."
• Task bead: "Review the attached pull request diff for correctness bugs."
• Constraint bead: "Ignore style nits. Only flag things that will break at runtime or in production."
• Output format bead: "Return a numbered list. One line per bug. No preamble."

A monolithic prompt versus the same instructions broken into beads.

String them together and you get a prompt. Change one bead and you get a different prompt, without touching the other three.

Debug one bead at a time

The reason this matters more than it sounds like it should: when a model output goes sideways, a forty line paragraph gives you no way to isolate the cause. Was it the persona confusing the tone? The constraint contradicting the task? You end up rewriting the whole thing and hoping.

With beads, you swap one out, rerun, and see if the problem moves. It's the same instinct as bisecting a bug in code. You don't rewrite the whole file, you isolate the line.

Build a reusable bead library

Once you've got beads, stop copy pasting them between prompts. A small Python library pays for itself fast:

from dataclasses import dataclass
 
@dataclass
class Bead:
    name: str
    content: str
 
def string_beads(*beads: Bead) -> str:
    return "\n\n".join(bead.content for bead in beads)
 
persona = Bead("persona", "You are a blunt code reviewer who has shipped production Python for a decade.")
task = Bead("task", "Review the attached pull request diff for correctness bugs.")
constraint = Bead("constraint", "Ignore style nits. Only flag things that will break at runtime or in production.")
output_format = Bead("output_format", "Return a numbered list. One line per bug. No preamble.")
 
prompt = string_beads(persona, task, constraint, output_format)

Swap constraint for a stricter one on a security sensitive repo, or swap output_format for JSON when another program needs to parse the result. The other three beads never change. This is a toy example. Real bead libraries end up with a dozen constraint variants and a handful of output formats, but the shape stays this simple.

Load beads progressively

Not every bead should load every time. My skillit plugin builds Claude Code skills around exactly this idea: a skill's frontmatter loads in every session no matter what, the body loads whenever the skill actually runs, and reference material only loads when the skill needs it. The skillit docs put it bluntly: the description loads in every session, so tight wins.

Think of frontmatter as your cheapest, most mandatory bead, and a reference file as an expensive bead you only pull off the shelf when the job actually calls for it. Loading everything up front defeats the point of breaking things into beads in the first place.

Compose beads with code, not by hand

The real payoff shows up when the shape of the prompt has to change based on input. A support bot might swap in a different constraint bead depending on a customer's plan tier. A skill builder might assemble a different set of beads depending on whether it's validating a new skill or auditing an existing one, which is exactly what skillit's skill-audit and skill-optimize commands do under the hood.

Worth being upfront about something here: I've also seen "bead" used for a different, related pattern. In a post on my Camino agent, and in a piece I wrote for Postman, a bead is a unit of independent work in an execution graph, wired up so that beads with no dependency on each other run in parallel instead of one at a time. That's not the same thing as a chunk of prompt text, but it rhymes: both patterns replace one big monolith, a giant prompt, or one long sequential loop, with small, composable, swappable pieces. Same instinct, two different layers of the stack.

Know when a loop still wins

Beads are about structure, what's inside the prompt or the workflow. Loops are about repetition, how many times you run something before you're done. If the job is genuinely "do this again until a condition passes," like a fix that needs to clear a test suite, you want a loop. If the job is "assemble the right instructions for this specific case," you want beads.

Most agents I've built end up needing both: a set of beads strung together into one turn's worth of instructions, run inside a loop that repeats until the stop condition is met.

If you're building your own Claude Code skills, skillit will score how lean your beads actually are. If you want more breakdowns like this, subscribe to the site or follow along on YouTube at @seeqcode.