CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

bmad-facilitate

Coaches the user through writing, updating or validating a document. Use when invoked by skill name only

Quality

78%

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-facilitate/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 an exceptionally dense, action-first facilitation playbook: concrete commands, precise behavioral thresholds, and a numbered Finalize sequence with genuine validation and re-validation loops. Its weaknesses are the readability cost of the compression — run-on sentences packing many clauses — and a monolithic main file where a few well-separated concerns (headless payload, HTML view rendering) could be pushed to the existing references structure.

Suggestions

Break the longest multi-clause sentences (the calling-agent parameter list in 'On activation', the render_view command and view-comment logic in 'Close') into short steps or a small list so the sequence survives a single reading.

Move the headless JSON payload specification and the Close/HTML-view rendering rules into reference files under references/, linked with one clear line each, to slim the main file further.

Add a brief explicit list of the shipped references (rubric-general.md, rubric-planning.md) and scripts (check_ids.py, render_view.py) near the top so a reader discovers the bundle without parsing the naming convention.

DimensionReasoningScore

Conciseness

The body is maximally lean: every sentence carries operational instruction, no concept Claude already knows is explained, and there is zero padding, matching 'Lean and efficient; assumes Claude's competence; every token earns its place'. It is not 4 because there are no sections of over-explanation to trim — the only cost of the compression is readability, not token waste.

5 / 5

Actionability

Concrete, copy-paste-ready commands appear throughout ('uv run {project-root}/_bmad/scripts/memlog.py append --workspace {run} --type <fact|decision|...> --text "..."', 'uv run {skill-root}/scripts/check_ids.py {run}/{id}-{slug}.md', 'count the body with wc -w') alongside precise behavioral rules ('No message asks more than two things', 'up to three' high-impact questions). It falls short of 5 due to minor gaps: the headless JSON payload keys are named but their exact shape is not specified, and the Close section's render_view invocation with its nested view/comment logic takes several readings to reconstruct.

4 / 5

Workflow Clarity

The process is explicitly sequenced (activation 1-3, intents, facilitation paths, Finalize 1-9) with real validation checkpoints and feedback loops — 'fix every undefined, duplicate and withdrawn hit', 'rerun check_ids.py and fix every toc hit', 'Log each pass only once its edits are in' — matching 'Clear sequence with most checkpoints present'. It is not 5 because the extreme compression leaves some steps and conditions ambiguous (e.g., the calling-agent parameter paragraph and the template-extension resolution rules require re-reading to reconstruct the exact order of operations).

4 / 5

Progressive Disclosure

Bundle references are real, one level deep, and clearly signaled: '{skill-root}/references/<name>.md' resolves to the shipped references/rubric-general.md and rubric-planning.md, and scripts/check_ids.py and scripts/render_view.py both exist and are invoked by exact path. It is not 5 because the single SKILL.md carries ~4,500 words with sections (the headless JSON payload spec, the Close/HTML-view rendering rules) that could live in reference files, and the rubric references are named only indirectly through a naming convention rather than an explicit listing.

4 / 5

Total

17

/

20

Passed

Description

62%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 concise, honest, and answers both what and when, with an explicit (if deliberately restrictive) trigger clause that minimizes conflict risk. Its main weakness is genericness: the actions and domain are stated at a high level with no concrete document types or natural trigger phrases.

Suggestions

Name the concrete document types coached (e.g., PRDs, technical briefs, planning docs) to sharpen the 'what' beyond the generic 'a document'.

Add one or two natural trigger phrases users would say (e.g., 'help me draft', 'review this doc against its purpose') so the skill surfaces even in name-only contexts like skill listings.

State one distinguishing capability of the coaching (e.g., section-by-section facilitation with tagged assumptions) to separate it from plain document-writing skills.

DimensionReasoningScore

Specificity

The description names the domain ("a document") and three actions ("writing, updating or validating") but the actions are generic — it never says what kinds of documents or what coaching involves, matching 'Names domain and 1-2 concrete actions, but not comprehensive'. It is below 4 because the actions lack the specificity of 'Extracts text from PDF files, fills forms' — no concrete deliverables or methods are named.

3 / 5

Completeness

Both parts are present: 'what' ('Coaches the user through writing, updating or validating a document') and an explicit 'when' clause ('Use when invoked by skill name only'), matching 'Has both what and when; when could be more explicit or specific'. It is not 5 because the 'when' names no concrete trigger phrases, and not 3 because the trigger guidance is explicit rather than merely implied.

4 / 5

Trigger Term Quality

Natural keywords like "writing", "updating", "validating" and "document" are present and would be said by users, but common variations ("draft", "review", "PRD", "brief") are missing, fitting 'Some relevant keywords but missing common variations or synonyms'. It is not 4 because the explicit trigger clause 'Use when invoked by skill name only' supplies no concrete trigger phrases at all, leaving keyword coverage thin.

3 / 5

Distinctiveness Conflict Risk

The coaching framing ('Coaches the user through') distinguishes it from skills that directly write or process documents, and 'invoked by skill name only' eliminates auto-trigger conflict by design, fitting 'Mostly distinct; minor overlap risk with closely related skills'. It is not 5 because 'a document' is broad and several document-authoring skills could claim the same territory were it not for the name-only restriction.

4 / 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-facilitate/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.