BMAD Method Compiles Its Prompts, In Five Skills Of Thirty

SnackOnAI Engineering | Senior AI Systems Researcher | Technical Deep Dive | September 18, 2026

BMAD's interesting idea is not agile ceremony for agents. It is treating prompts as source code that gets compiled, validated in CI, and shipped with reference integrity. That idea is live in one sixth of the codebase.

What this covers: the skill anatomy, the bootstrap-and-render pattern, conditional compilation of workflows, and the validation pipeline. What this excludes: the six ecosystem modules, the web bundles, and the docs site.

BMAD Method is an MIT-licensed methodology from BMad Code, LLC that installs as skills into Claude Code, Codex and other tools that support them. npx skills add bmad-code-org/BMAD-METHOD and you have thirty skills covering brainstorming, product briefs, PRDs, architecture, sprint planning, build, code review, UX and retrospectives.

The pitch is right-sized process. Small changes go straight to build; large ones get planning depth. That is a project-management claim, and it is not what makes the repository worth reading.

Look at the shape of the codebase instead:

It is a prompt corpus with a build system attached. The Python is not runtime, it is a renderer, three validators, release stamping and a bundler. The product is the markdown.

Five languages of documentation, Korean, Chinese, French, Vietnamese and Czech, account for two fifths of all markdown in the repository. That is more internationalization than most commercial developer tools carry, and it tells you where the adoption is.

Caption: Follow the byte counts down the middle. A 1,639 byte stub reaching 77,273 bytes of workflow is the whole architectural idea, and the box beneath it shows how few skills actually use it.

Three decisions carry this, ranked.

One, the skill is a directory and the workflow is generated. SKILL.md for bmad-build is a bootstrap that runs a renderer and reads back a single absolute path. Everything the agent executes was produced for this project, this route and this review level.

Two, the route is a compile flag, not a runtime branch. --set workflow.route=oneshot and --set workflow.review=thorough select which workflow gets built. The "right-sized process" promise is implemented as conditional compilation rather than as instructions the model must read and then decide to skip.

Three, customization is a separate file from the manifest. Every skill carries both module-manifest.toml, which holds module, version and update_source, and customize.toml, which holds user overrides. Splitting them is what makes bmad update safe: your changes live in a file the updater does not own.

That description is the most carefully engineered text in the repository, and it is worth reading twice. Roughly half of it is negative scoping: when not to fire. Trigger precision is the hardest part of skill design, because a skill that activates on typo fixes trains the user to stop trusting it.

Caption: The last line is the load-bearing one. On failure the agent is forbidden from reading the raw markdown and improvising, which is the failure mode every prompt library has and almost none forbid.

Caption: Broken cross-references between prompt files fail CI. That is a linker for prose, and it is the single most transferable idea in this repository.

Caption: deletion-check.md is the detail worth stealing outright. Somebody noticed that reviewing what an agent removed is a different job from reviewing what it added, and gave it its own reviewer.

Input: a small bug fix delegated to bmad-build, with the oneshot route.

Step one, trigger. The model matches the description's positive scope, a bug fix, and checks it against the negative scope. Not a typo, not formatting, not a configuration-hygiene edit. It fires.

Step two, bootstrap. The 1,639 byte SKILL.md is all the model has loaded. It runs render_skill.py once, with --set workflow.route=oneshot.

Step three, render. The renderer reads the skill directory, the project's _bmad configuration and customize.toml, and writes one workflow.md. It prints a single absolute path to stdout.

Step four, execute. The model reads that path and follows it. For the oneshot route that is step-oneshot.md. It never loads step-02-plan.md through step-05-present.md.

Step five, the arithmetic. The resident cost of having this skill installed is about 409 tokens of description and bootstrap. The full skill is about 19,300 tokens. The stub is 2.1 percent of the payload, and the compiled workflow is a fraction of the remainder because the unused route never renders.

Step six, what happens if it breaks. If render_skill.py is missing, the instructions say to read the sibling bmad skill and run setup, then retry once. On any other failure, report and halt. There is no path where the agent reads workflow.md directly and improvises.

It works because it takes the context budget seriously in the place that actually costs you. Skill descriptions are resident: the model carries every installed skill's frontmatter in order to decide what to invoke. Thirty skills at full inline weight would be an enormous standing tax. Thirty bootstraps at roughly 400 tokens each is 12,000, and the workflows arrive only when invoked.

It works a second time because the validators make the prompts refactorable. You can move references/help.md and find out at commit time rather than when an agent hallucinates its contents.

What it trades away:

Consistency. Five skills compile, twenty five inline. Insight One.

A hard dependency on uv. The bootstrap runs a Python script through uv on every invocation. That is a second runtime alongside Node and your coding tool, and --no-cache means it pays startup each time.

Opacity. With the inline skills you can read the workflow in the repository. With the compiled ones you cannot know what the agent will actually execute without running the renderer against your project, because the output depends on your configuration and overrides.

A project-management frame around an engineering contribution. The README sells agile ceremony: briefs, PRDs, epics, sprint planning, retrospectives. The genuinely novel work is the skill compilation and the prose CI, and neither appears in the README at all.

Trademark friction. BMad and BMAD-METHOD are trademarks with a dedicated TRADEMARK.md, on an MIT repository. Legally ordinary, worth knowing before you fork and rename.

There is no moat in the methodology. Brief, PRD, architecture, epics, stories, build, review, retro is the standard agile decomposition, and the prompts implementing it are readable markdown anyone can copy.

The moat, to the extent there is one, is the build system for prose. A renderer that compiles workflows from a skill directory with route and review flags. A reference validator that resolves cross-file claims and rejects absolute path leaks. A deterministic skill validator running ten rules as a first pass to an inference-based one. Pre-commit hooks, yamllint, and two AI code reviewers wired into a corpus of 404 markdown files. That apparatus is months of unglamorous work, and it is why this repository can be refactored while most prompt libraries can only be appended to.

The second moat is trigger precision, accumulated one negative clause at a time. The bmad-build description names four categories it should skip. Every one of those clauses is a bug report someone filed after the skill fired on a typo fix.

The third is internationalization. Five full documentation locales and three translated READMEs, which is 40.6 percent of all markdown in the project. That is a distribution asset, not an engineering one, and it is larger than most commercial tools maintain.

Insight One: the architecture the repository is built around is used by one sixth of it.

Measure the stub against the payload for each skill and two populations appear:

Grep for render_skill.py across all thirty SKILL.md files and five match. Twenty five put their workflow directly in the file the model always carries.

So the compression ratio inside this one repository ranges from 3.0x to 47.1x depending on which skill you invoke, and there is no note in the README explaining why.

The generous reading is that this is a migration in progress, and the fact that the flagship build, review and retrospective skills went first suggests the highest-traffic paths were converted first. That is the right order.

The practical reading matters more if you are installing this. Your standing context cost is dominated by the twenty five inline skills, not the five compiled ones. bmad-prd alone carries 13,867 bytes of resident description and instruction, which is more than eight bmad-build stubs. If you install the full set and wonder where your context went, that is where.

Insight Two: they built continuous integration for prose, and that is the part worth copying.

Three things run against this markdown corpus.

validate_file_refs.py resolves cross-file references. When a prompt says see references/help.md, that is a claim about the filesystem, and this checks it. It also rejects absolute path leaks, /Users/, /home/, C:\, which is the classic way a contributor's local path ends up shipped in a prompt. And it enforces that no file sits directly under skills/, so everything belongs to exactly one skill.

The rule has a refinement that tells you it has been through a false-positive cycle: only paths whose first directory actually exists are checked, because a path whose directory is absent is prose, an example or a runtime output, rather than a reference. Somebody shipped the naive version, it cried wolf, and they taught it the difference between a reference and an example of a path.

validate_skills.py runs ten deterministic rules covering frontmatter presence, name format and forbidden substrings, and describes itself as a fast first-pass complement to the inference-based skill validator. So there are two validators, one deterministic and one using a model, layered deliberately.

Then .pre-commit-config.yaml, .yamllint.yaml, and both greptile.json and .coderabbit.yaml. Two AI code review services, on a repository that is four hundred markdown files and forty seven Python scripts.

This is the transferable idea, and it has nothing to do with agile. If prompts are your product, they are source code, and source code that nothing validates decays. Most teams have a prompts/ directory with no tests, no reference checking and no linter, and discover the rot when an agent confidently follows an instruction pointing at a file that moved six months ago.

A reference validator is about two hundred lines. It is the highest-value thing in this repository and the easiest to steal.

The bmad-build skill costs about 409 tokens to have installed and reaches about 19,300 tokens of workflow. The stub is 2.1 percent of what it unlocks, and the route you did not choose is never rendered at all.

Every skill system has the same tax. The model must hold every installed skill's description in context permanently, just to decide what to invoke. Discovery is resident, execution is occasional, and most designs price them the same by putting the workflow in the file the model always carries.

BMAD's answer on its compiled skills is to make SKILL.md a bootstrap. It holds a description, a command, and error handling. The command runs a renderer that reads the skill directory plus your project configuration and your customize.toml, then prints one absolute path. The agent reads that and follows it.

Two consequences fall out, and the second is the interesting one.

The resident cost drops by a factor of roughly forty. And because route and review level are flags on the renderer rather than conditions inside the prompt, the workflow the agent receives contains only the path it needs. A oneshot build never loads the five-step plan. That is not the model skipping instructions, it is the instructions not existing.

The distinction matters because models are unreliable at skipping. Give one a workflow saying "if the change is trivial, go straight to implementation", and you have paid for the full document and you are relying on a judgment call. Compile the trivial path instead and there is nothing to judge.

If you maintain a prompt library of any size, the question to ask is what fraction of your resident context is instructions for paths this invocation will not take. For most libraries the answer is most of it, and the fix is a renderer and two flags.

AI coding assistants are good at writing code and bad at knowing what to build. Hand one a vague request and it fills the gaps with assumptions, then turns those assumptions into code you live with.

BMAD is a set of instructions that slots into assistants like Claude Code and walks them through the parts people skip: what problem this solves, how the pieces fit, what to check afterwards.

The interesting engineering is not the process. It is how the instructions are delivered.

An assistant has limited working memory, and everything it might do has to stay there so it knows the option exists. Thirty detailed procedures would crowd out the work.

So the best-built parts of BMAD keep only a summary in memory, a few hundred words. When you actually invoke one, a small program assembles the full procedure on the spot, tailored to your project and to how thorough you asked it to be. A quick fix gets a short procedure. A large feature gets the long one. The assistant never reads the version it does not need.

Think of a restaurant menu versus a recipe binder. The menu stays on the table, one line per dish. The recipe only comes out when you order, and only that recipe.

The transferable lesson is that instructions written for machines are a kind of source code, and source code needs a build system and tests. This project has both, applied to plain English.

BMAD Method is an MIT agile methodology that installs as thirty skills into AI coding tools, and its genuine engineering contribution is unrelated to agile: the flagship skills ship a 1,639 byte bootstrap that runs a Python renderer to compile a workflow from route and review flags, so the agent loads about 409 tokens to reach 19,300 and never receives the branch it did not request. Only five of thirty skills use that pattern while twenty five inline everything, and the repository runs reference-integrity validation, two skill validators and two AI code reviewers against a corpus of 404 markdown files. It matters because it is the clearest working example of treating prompts as compiled, validated source rather than as text.

The habit from this issue: measure your prompt library the way you would measure a binary. Bytes resident versus bytes reachable, and what fraction of the resident text describes paths this invocation will not take. One wc -c across a skills directory told the whole story here.

SnackOnAI runs this teardown weekly on the systems engineers actually deploy, agent frameworks, prompt architectures, serving stacks, and the repositories whose best ideas never reach their own README. No announcements, no press release summaries. Subscribe at snackonai.com and join 10,000+ engineers reading it.

Forward this to whoever on your team maintains a prompts/ directory that nothing validates.

Every customer signal is captured in one shared context layer, always current and compounding. Agents and workflows build pipeline, chase every buying signal, and move deals forward, an always-on revenue engine running alongside your team.

With Attio, you’ll get:

Teams like Parallel, Turbopuffer, and Wordsmith build on Attio. Are you one of them?

Get started now