CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

bmad-architecture

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"

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A high-quality instruction skill body: lean, dense with non-obvious doctrine, fully sequenced workflows with explicit validation gates and error-recovery fallbacks, and a genuinely one-level-deep bundle. Remaining polish is minor — deduplicating repeated activation fallback text, showing one inline example of an AD/memlog entry, and giving the spine template an explicit path.

Suggestions

Deduplicate the near-identical 'Script not found → offer bmad setup' fallback text in Activation steps 1 and 2 into a single shared fallback rule, freeing tokens in the most token-expensive section.

Include one minimal inline example of a logged memlog decision entry and a resulting AD-n (Binds/Prevents/Rule) so the common create path is executable without loading the template.

Name the spine template explicitly (e.g. 'seed the spine from assets/spine-template.md') alongside the {workflow.spine_template} variable so the asset is discoverable from the body without config resolution.

DimensionReasoningScore

Conciseness

The body is exceptionally dense with no explanations of concepts Claude already knows — every section carries skill-specific doctrine (the spine test, altitude rules, memlog mechanics). It falls just short of anchor 5 because of minor redundancy: the 'Script not found… offer to run the bmad skill's setup, installing bmad first' fallback is repeated nearly verbatim in Activation steps 1 and 2, and the Coaching-path default is restated three times across sections.

4 / 5

Actionability

Concrete, copy-paste-ready commands throughout ('uv run {project-root}/_bmad/scripts/memlog.py init --workspace …', 'uv run … resolve_customization.py --skill … --key workflow', 'npx skills add bmad-code-org/BMAD-METHOD --skill bmad') with explicit fallback paths for each failure mode. It misses anchor 5 only because artifact shapes — an AD-n with Binds/Prevents/Rule, a memlog entry — are never exemplified inline, relying on the config-mediated template and bundle files for the common cases.

4 / 5

Workflow Clarity

Multi-step processes are clearly sequenced (numbered Activation, 8-step Finalize, Update, Validate) with explicit validation checkpoints (deterministic lint_spine.py pass, reviewer gate, reconcile-inputs subagents, one-at-a-time blocker triage) and genuine feedback loops ('Resolve before polish', 'If validation fails' style fallbacks like re-running after setup or handoff). This matches the top anchor including its checklist-for-complex-processes criterion, which reviewer-gate.md's good-spine checklist supplies.

5 / 5

Progressive Disclosure

The body is well-sectioned, and the two reference files (references/headless.md, references/reviewer-gate.md) exist, are one level deep, and are clearly signaled with load conditions ('Headless… follow references/headless.md for the whole run', 'full mechanics in references/reviewer-gate.md. Load it when finalizing or validating'). The minor gap keeping it from anchor 5: assets/spine-template.md is reachable only through the {workflow.spine_template} config variable rather than an explicit path, and the long dense body could lean slightly more on the bundle.

4 / 5

Total

17

/

20

Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: concrete, third-person, and explicitly paired with quoted user trigger phrases covering create, update, and validate intents. The main residual gaps are missing common synonyms in the trigger list and a slightly abstract statement of what the produced artifact contains.

DimensionReasoningScore

Specificity

The description lists several concrete actions — 'Creates, updates, or validates one; works from a ticket file' plus 'work out and record the architecture decisions' — but stops short of comprehensive coverage (e.g. distilling an existing codebase or producing human-facing artifacts is only implied by 'with an existing codebase or architecture document beside it'). It fits anchor 4 (several specific actions, minor gaps) better than 3 (only 1-2 actions) or 5 (comprehensive enumeration).

4 / 5

Completeness

It clearly answers both: the 'what' ('Work out and record the architecture decisions that keep separately built parts of a system consistent, in a short architecture document') and an explicit 'Use when the user says…' clause with concrete quoted trigger phrases, all in third-person voice. This matches the top anchor; anchor 4 would require the 'when' to be less explicit or specific, which it is not.

5 / 5

Trigger Term Quality

Four quoted natural phrases users would plausibly say — "create the architecture", "create technical architecture", "architecture spine", "create a solution design" — give good keyword coverage, though common variations like 'solution architecture', 'tech design', or 'architecture document' are absent. Not anchor 3 (coverage is genuinely good, not just 'some relevant keywords') nor anchor 5 (no synonyms or extension-level variants).

4 / 5

Distinctiveness Conflict Risk

The spine/ticket framing and the term 'architecture spine' give it a clear niche with distinct triggers, but phrases like 'create a solution design' and 'create technical architecture' could plausibly overlap with related design or planning skills. Mostly distinct with minor overlap risk (anchor 4) rather than minimal conflict risk (anchor 5), and clearly above anchor 3.

4 / 5

Total

17

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

bmad-code-org/BMAD-METHOD

Path

skills/bmad-architecture/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.