BMad Architecture Skill for Claude: Write the Architecture Spine

Coaches you through the design decisions that keep separately built parts of a system consistent, and writes them into a short document.

Installs: 13.3K; on skills.sh
Stars: 54.9K; on GitHub
Files: 7; besides SKILL.md
Updated: Nov 2026; last repo commit

bmad-architecture makes Claude produce an "architecture spine": a short document that fixes only the decisions two independent builders could otherwise get wrong, such as the design paradigm, boundary rules, how state changes and who owns shared data. Everything else is left as a minimal starting point for the code to own. By default Claude coaches you with open questions instead of drafting for you, and a Fast path drafts everything with [ASSUMPTION] tags for you to correct.

Say "create the architecture", "create technical architecture", "architecture spine" or "create a solution design" and it triggers. It works from a ticket file and runs uv scripts from your project's _bmad folder, so you need the rest of the BMad set installed and bmad setup done. It can create, update or validate a spine.

Good for

Developers and tech leads who need an architecture doc before several people or agents build in parallel
Teams adopting BMad who have a ticket with requirements ready
Anyone inheriting a codebase who wants its existing conventions written down

Install bmad-architecture

Claude Code

Copy this prompt.

Install the bmad-architecture skill in Claude Code. Run this command:

/plugin marketplace add bmad-code-org/bmad-plugins
/plugin install bmad-method@bmad
/plugin install bmad-toolbox@bmad

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires uv.

Install the whole BMad set, not just this skill: it calls scripts and sibling skills that the set provides. After installing, open your coding tool in the project and ask the bmad skill to run bmad setup. Every route needs uv (the README says both routes need it for setup and Python scripts). This is the v7 preview alpha, so expect breaking changes between updates. Plugin names differ between sources: the BMAD-METHOD README says to install bmad-method and bmad-core-tools, but the bmad-plugins README and its marketplace manifest list bmad-method and bmad-toolbox, and the bmad skill sits in the toolbox plugin's skills folder. Use the names that /plugin shows after you add the marketplace. Pick one route, not both.

From the project README. Source.

What's in the skill

When it loads

Work out and record the architecture decisions that keep separately built parts of a system consistent, in a short architecture document. Creates, updates, or validates one; works from a ticket file, with an existing codebase or architecture document beside it. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design"

Sections in SKILL.md

Overview
How you work
Read the input to know the job
How a run works
Resolution rules
On Activation
Reviewer Gate
Finalize
Update
Validate

Key facts

Author: bmad-code-org (BMad Code); the plugin marketplace lists Brian (BMad) Madison as owner
License: GitHub detects none for the repo (NOASSERTION); the README and plugin marketplace say MIT
Installs on skills.sh: 13,344 as of 2026-11-02
GitHub stars: 54,859 for the whole BMAD-METHOD repo
Last commit to the repo: 2026-11-01
Files in the skill: 8 files including SKILL.md: bmod.toml, customize.toml, assets/spine-template.md, references/headless.md, references/reviewer-gate.md, scripts/lint_spine.py, scripts/tests/test_lint_spine.py
Needs: uv (README), plus the bmad setup skill so the _bmad/scripts folder exists
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Builds a new spine from your ticket, coaching you through each decision.
Seeds the spine file from its template in an architecture-<slug> folder, logs every decision to .memlog.md, then distills the spine from that log at the end.
Try: “Create the architecture for this ticket.”
Write · Create (default)
You choose: Claude pulls decisions out of you, or drafts all with tagged assumptions.
Coaching is the default and uses open questions. Fast drafts the whole spine with [ASSUMPTION] tags you correct in review. The big calls (paradigm, stack or starter, major boundaries) are shown with alternatives before you choose.
Read · Coaching path or Fast path
Amends an existing spine and keeps its AD numbers stable.
Resumes from the .memlog.md, records the change, re-writes the spine and runs the reviewer gate. New decisions get the next AD number; none are renumbered.
Write · Update
Critiques a spine without changing it and builds an HTML report.
Runs the reviewer gate against the spine and delivers an HTML plus markdown report, then offers to turn the findings into an update.
Write · Validate
Runs lint_spine.py, then reviewer subagents in parallel.
A deterministic lint pass catches placeholders, duplicate AD IDs, missing Binds, Prevents or Rule lines and unpinned stack versions. Then a rubric reviewer and the configured lenses write reviews into a reviews folder.
Runs code · Reviewer gate
Distills, reconciles inputs, reviews, triages, polishes and closes.
Reviewer fixes land before polish. The close sets the spine's status to final and logs an event.
Write · Finalize (8 steps)
Runs the whole job without a user, following references/headless.md.
Used when no interactive user is present. references/headless.md says headless skips only the human picking from the menu, never the reviewers.
Write · Headless mode
Appends one line per decision, constraint, version or question to .memlog.md.
The run's working memory. Entry types are decision, constraint, version, assumption, question, direction and event.
Runs code · memlog.py init / append

From the official docs

Permissions

Medium risk

It writes files into your project, runs uv scripts, uses web lookups and starts reviewer subagents. Commit or back up first, and check what it wrote.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It writes files and reads your code
It creates a run folder under your output folder holding the architecture file, a .memlog.md and review files. On an existing codebase it reads enough real code to base the decisions on it. Commit or back up first and check what it wrote. github.com
It looks things up on the web
SKILL.md says to verify any named technology's current version and fit on the web, and to check a starter's live defaults. Do not put secrets into the prompts you give it. github.com
It spawns reviewer subagents
The reviewer gate runs a script, lint_spine.py, then dispatches reviewers as parallel subagents that write review files. A validate run also builds an HTML report. Expect extra token use on large specs. github.com
It runs uv scripts from your project
SKILL.md has Claude run resolve_customization.py, resolve_config.py and memlog.py with uv from a _bmad/scripts folder in your project. Those scripts come from the bmad skill, not from this folder, so read them there if you want to know what they do. github.com
Project override files steer Claude
Claude reads customize.toml plus optional team and personal override files, runs their activation steps and external handoffs, and loads their persistent facts. Anyone who can edit those files in your repo can change what the skill does, so review them in pull requests. github.com

Technical details

Sign-in and keys	SKILL.md names no sign-in or API key.
Scopes	Runs uv scripts (resolve_customization.py, resolve_config.py, memlog.py, lint_spine.py) Writes an architecture-<slug> folder with the spine, .memlog.md and reviews Web lookups for technology versions

Questions

What does the bmad-architecture skill do?

It guides you to the few architecture decisions that stop separately built parts from drifting apart, and writes them into a short "spine" document. It can also update an existing spine or review one without changing it.

How do I install bmad-architecture?

Use the install box above and install the whole BMad set. The skill needs the scripts and sibling skills in it, so installing it alone does not work. Then ask the bmad skill to run bmad setup.

Does it need an API key?

SKILL.md names no API key. It needs uv, which the README lists as required for BMad setup and its Python scripts, and it uses web lookups to check technology versions.

Is bmad-architecture safe to run?

It writes a folder of files into your project, runs uv scripts, looks things up on the web and starts reviewer subagents. Commit or back up first, and check what it wrote. The Permissions section lists the details.

Do I need a ticket first?

It works best from a ticket file with a Requirements section. With none, SKILL.md suggests asking Sofia (bmad-agent-po) to write the requirements first, or it captures the missing answers into the ticket's .memlog.md.

bmad-architecture vs bmad-agent-architect?

bmad-architecture is the workflow that produces the spine. bmad-agent-architect is the Winston persona whose menu item CA calls it. You can invoke bmad-architecture directly.

Information

updated Nov 2, 2026

Repository: bmad-code-org/bmad-method
Folder: skills/bmad-architecture

bmad-code-org/bmad-method skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 8

BMAD-METHOD README · github.com
bmad-plugins README · github.com
bmad-architecture SKILL.md · github.com
reviewer-gate.md · github.com
bmad-architecture headless.md · github.com
bmad-agent-architect customize.toml · github.com
customize.toml · github.com
bmad skill memlog.py · github.com