CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

bmad-product-brief

The earlier product brief workflow, kept for comparison with John the Product Manager (bmad-agent-pm), who now coaches product briefs. Use when the user names bmad-product-brief; otherwise use John.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/bmad-product-brief/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.

This is a strong instruction-style skill body: activation, three intent modes, and finalize are each sequenced with concrete commands, explicit failure branches, and machine-readable headless output contracts, while keeping the brief template properly externalized. The only real costs are a duplicated setup-fallback paragraph in activation, an unwieldy single-paragraph Discovery section, and template access that is mediated by config placeholders rather than direct file references.

DimensionReasoningScore

Conciseness

The body is dense and directive with no explanations of concepts Claude already knows ("Coach, do not quiz", "Extract, don't ingest"), but the BMad setup fallback ("Offer to run the `bmad` skill's setup, installing `bmad` first ... `npx skills add bmad-code-org/BMAD-METHOD --skill bmad`") is repeated nearly verbatim in activation steps 1 and 5, and the Discovery section is one long wall paragraph. These minor duplications keep it below the lean-everything-earns-its-place anchor 5, while the overall efficiency clearly exceeds a 3.

4 / 5

Actionability

Guidance is copy-paste ready for an instruction-only skill: exact commands with full arguments (`uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <decision|change|override|assumption|event> --text ...`), exact output conventions (`brief-{slug}/brief-{slug}.md`, YAML frontmatter fields), concrete JSON status schemas for headless mode, and enumerated fallback branches for every failure case. This matches the fully executable anchor with no meaningful gaps.

5 / 5

Workflow Clarity

Activation is a numbered sequence with explicit failure branches and retry loops ("Script not found ... then run the command again"), a final confirmation gate ("confirm every entry was executed in order before proceeding"), headless `blocked` halting on ambiguity, and handoff failure handling ("If a named tool is unavailable, skip that handoff and flag it"). The minor gap is that the parallel subagent passes (Discovery research, Finalize doc-standards polish) have no verification of their results, which fits "clear sequence with most checkpoints present" rather than the explicit-feedback-loops anchor 5.

4 / 5

Progressive Disclosure

The body is well-sectioned (Overview / On Activation / Intent Operating Modes / Headless Mode / Discovery / Constraints / Finalize) and the brief template is appropriately externalized to assets/brief-template.md rather than inlined. However, the body reaches that file only through the `{workflow.brief_template}` placeholder resolved by the customization mechanism rather than a clearly signaled path, so navigation depends on runtime config — a minor organization gap that fits anchor 4 rather than the clearly-signaled one-level-deep references of anchor 5.

4 / 5

Total

17

/

20

Passed

Description

61%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 is highly distinctive and conflict-safe, with an explicit use trigger and explicit routing away from the successor skill, but it is thin on stating the skill's own capabilities — the concrete actions (conversational coaching to craft, refine, and pressure-test product briefs) must be inferred. Adding one sentence of what this skill does and natural trigger phrases would lift specificity and completeness.

Suggestions

State the skill's own capabilities directly (e.g., "Conversationally coaches the user to craft, refine, or pressure-test a product brief") instead of defining it only by its legacy status and relation to bmad-agent-pm.

Add natural trigger phrases users would say beyond the skill name, such as "product brief", "write a brief", or "refine our brief", to broaden keyword coverage.

Keep the explicit routing clause ("otherwise use John") — it is the description's strongest asset for conflict avoidance.

DimensionReasoningScore

Specificity

"The earlier product brief workflow, kept for comparison" names the domain, but the only action verbs ("coaches product briefs") describe John (bmad-agent-pm), not what this skill itself does, so the actions of this skill remain minimal or generic. It is not a 1 because the domain and role are clearly identified, and not a 3 because no concrete actions performed by this skill are listed.

2 / 5

Completeness

The "when" is explicit and specific ("Use when the user names bmad-product-brief; otherwise use John") and the "what" is present ("The earlier product brief workflow"), but the what describes the skill's legacy status rather than what it does when invoked, so it falls between the clear-both anchor 4 and the fully concrete anchor 5.

4 / 5

Trigger Term Quality

"Use when the user names bmad-product-brief" provides an explicit trigger with the keywords "product brief" and "bmad-product-brief", but common natural variations a user would say ("write a brief", "refine the brief", "pressure-test the brief") are missing. This matches "some relevant keywords but missing common variations or synonyms" rather than the good coverage of a 4.

3 / 5

Distinctiveness Conflict Risk

The description explicitly disambiguates against its closest sibling skill ("kept for comparison with John the Product Manager (bmad-agent-pm)"; "otherwise use John") and triggers only when the user names it, giving a clear niche with minimal conflict risk. It actively manages the one real overlap, so it fits the top anchor rather than 4.

5 / 5

Total

14

/

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-product-brief/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.