CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

bmad-agent-architect

System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect

Quality

75%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/bmad-agent-architect/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

82%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.

The body is a tightly written, fully executable activation workflow: exact commands with defined placeholder semantics, explicit failure fallbacks, and clear sequence with validation checkpoints. Its main weaknesses are a repeated persona-persistence instruction and a missing fallback for the config-resolution step, plus somewhat dense inline detail.

Suggestions

State the persona-persistence rule once (e.g. only in Step 8's closing line) and remove the redundant repetitions in Step 3 and Step 6.

Add a fallback for Step 5's resolve_config.py (e.g. manual key lookup in _bmad config files) mirroring the resolver-script fallback in Step 1.

Consider moving the TOML merge rules and the menu dispatch/install rules into a short reference file to keep SKILL.md a lean overview.

DimensionReasoningScore

Conciseness

The body is dense, imperative, and explains nothing Claude already knows — placeholders, merge rules, and dispatch logic are stated in minimal space. However, persona persistence is stated three times (Step 3's closing paragraph, Step 6's icon instruction, and Step 8's closing line "Winston stays active... until the user dismisses him"), which is more repetition than the lean anchor-5 permits.

4 / 5

Actionability

Commands are exact and copy-paste ready ("uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent"), with placeholder resolution defined upfront, precise fallback file paths and merge rules, a concrete menu column spec, and install commands for missing skills. Edge cases (script not found, script fails, skill not installed) are all explicitly handled.

5 / 5

Workflow Clarity

The 8-step activation sequence is clearly ordered with explicit checkpoints ("Stop and wait for input", "confirm every entry was executed in order... Do not begin the main workflow until all activation steps have been completed") and an error-recovery fallback for resolver-script failure. It is not 5 because Step 5's resolve_config.py has no documented fallback if it fails or keys are missing, unlike the equivalent handling in Step 1.

4 / 5

Progressive Disclosure

No bundle files exist, so this is a single-file skill; the ~70-line body is organized under clear headers (Overview, Conventions, numbered activation steps) with every external path (customize.toml, bmod.toml, _bmad scripts) fully specified and one level deep. It sits at anchor 4 rather than 5 because dense inline details like the TOML merge rules and the menu dispatch rules could be extracted, and the body slightly exceeds the under-50-lines threshold that would let well-organized sections alone score 5.

4 / 5

Total

17

/

20

Passed

Description

57%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.

The description has an explicit and reasonably distinct trigger clause anchored by a unique persona name, but it describes the skill only as a role title without naming any concrete actions or outputs. Trigger coverage is narrow, missing natural domain terms like "architecture" or "system design".

Suggestions

Replace the role-title "what" with 2-3 concrete actions or outputs, e.g. "Turns ticket requirements into technical architecture and design documents, recording trade-offs and technology choices".

Broaden the trigger clause with natural variations users would actually say, such as "Use when the user asks for the architect, mentions Winston, wants system architecture or technical design for a ticket, or asks for technology trade-off analysis".

State what the skill produces (architecture docs, design decisions) so the "what" answers concretely rather than by job title.

DimensionReasoningScore

Specificity

"System architect and technical design leader" names the domain clearly but contains no action verbs at all — fewer concrete actions than the anchor-2 example ("Processes PDF files"), yet far more domain-specific than the entirely-vague anchor-1 example ("Helps with documents"). It falls between the two anchors, so the even score applies.

2 / 5

Completeness

Both parts are present: a "what" ("System architect and technical design leader") and an explicit "Use when..." clause with concrete triggers. It is not 5 because the "what" is only a role title with no statement of concrete capability, and not 3 because the "when" is explicitly stated rather than implied.

4 / 5

Trigger Term Quality

The explicit triggers are "talk to Winston" and "requests the architect" — two relevant keywords, but common natural variations a user would say ("architecture", "system design", "technical design", "design trade-offs") are entirely absent. This matches anchor 3; it is not anchor 4 because core domain trigger terms are missing, not just a few.

3 / 5

Distinctiveness Conflict Risk

"Winston" is a highly distinctive persona name giving clear niche triggers, but "requests the architect" carries minor overlap risk with other architecture or design-related skills. This matches anchor 4 ("Mostly distinct; minor overlap risk") and not anchor 5, which requires minimal conflict risk.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

bmad-code-org/BMAD-METHOD

Path

skills/bmad-agent-architect/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.