CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

decision-record

Writes an architecture decision record (ADR). Use when the user says "record this decision", "write an ADR" or "we decided X, capture it".

Quality

91%

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

SKILL.md
Quality
Evals
Security

Quality

Content

100%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 exemplary short instruction-only skill: lean, fully concrete commands and path rules, an unambiguous workflow with an explicit approval checkpoint and an activation fallback, and appropriately self-contained organization.

DimensionReasoningScore

Conciseness

The 16-line body is lean with no padding: every sentence instructs ("Each option gets one line on why it lost", "A consequence is something that will cost effort or close a door, not a benefit restated") or sets the output quality bar ("a record a newcomer can read a year later"). Nothing re-explains concepts Claude already knows, so it fits the lean anchor rather than the minor-trimming anchor 4.

5 / 5

Actionability

Guidance is fully concrete and executable: the exact activation command ("uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative"), the exact fallback ("npx skills add bmad-code-org/BMAD-METHOD --skill bmad"), the precise output path pattern with its unset edge case, and named sections with per-item rules. As an instruction-only skill with copy-paste-ready commands, it matches the top anchor.

5 / 5

Workflow Clarity

The sequence is unambiguous: activate config (with a script-not-found fallback), mine the conversation, ask one question at a time, write four sections, "Show the draft and wait", then write the file on approval and tell the user the path. The approval gate is an explicit checkpoint and the activation fallback is an error-recovery loop; the operation is non-destructive so no validation cap applies.

5 / 5

Progressive Disclosure

The skill is under 50 lines, single-purpose, and has no bundle files (references/, scripts/, assets/ are absent), so there is nothing to push to separate files. The two clear sections ("On activation", "Writing the record") are well organized, which per the simple-skill guidance earns the top score.

5 / 5

Total

20

/

20

Passed

Description

78%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 that answers both what and when with concrete, naturally spoken trigger phrases in a distinct niche. Its only weaknesses are that it names a single action rather than enumerating what the skill concretely does, and a couple of common synonyms are absent.

Suggestions

Enumerate the concrete actions the skill performs (e.g., drafting the four standard ADR sections: Context, Decision, Options considered, Consequences) to raise specificity beyond a single action.

Add one or two common trigger synonyms such as "decision log" or "document this decision" to broaden natural-term coverage.

DimensionReasoningScore

Specificity

"Writes an architecture decision record (ADR)" names the domain plus one concrete action, matching the anchor for 1-2 concrete actions that are not comprehensive. It is more concrete than the generic anchor 2 ("Processes PDF files") but does not list several specific actions needed for anchor 4.

3 / 5

Completeness

It clearly states what the skill does ("Writes an architecture decision record (ADR)") and explicitly when to use it with concrete quoted trigger phrases ("Use when the user says..."). This matches the anchor requiring both what and when with concrete trigger phrases.

5 / 5

Trigger Term Quality

The quoted phrases "record this decision", "write an ADR" and "we decided X, capture it" are natural things a user would say, and the full term plus acronym ("architecture decision record (ADR)") is present. A few natural synonyms such as "decision log" or "document this decision" are missing, so it falls just short of the comprehensive anchor.

4 / 5

Distinctiveness Conflict Risk

The ADR niche is clear and "write an ADR" is unambiguous, but the softer triggers "record this decision" and "capture it" could plausibly overlap with general note-taking or documentation skills. Mostly distinct with minor overlap risk, fitting anchor 4 rather than the minimal-conflict anchor 5.

4 / 5

Total

16

/

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-toolsmith/shapes/plain-skill/assets/sample-skill/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.