CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architecture-decision

Document an architectural decision — record the decision and rationale, retain into Hindsight, and update CLAUDE.md if needed.

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 ./devflow-plugin/skills/architecture-decision/SKILL.md

The canonical home for this skill is architecture-decision in AndreJorgeLopes/devflow

SKILL.md
Quality
Evals
Security

Quality

Content

75%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 well-structured, actionable instruction-only skill: a fillable ADR template, explicit retain fields, approval gates, and a confirmation report. It scores solidly but not top marks due to the unspecified ADR save location, missing failure/recovery paths (user rejection, unavailable tools), and duplicated diagram guidance between the opening blockquote and Step 2.

Suggestions

Consolidate the diagram guidance: merge the opening diagram-complexity blockquote with Step 2's diagram paragraph so the topic is covered once.

Specify where the ADR is persisted (e.g., a `decisions/` directory or inline in a decision log) so the retain and embed steps have a concrete destination.

Add a brief recovery path for Step 3: if the user requests changes to the draft ADR, revise and re-present before retaining into Hindsight.

DimensionReasoningScore

Conciseness

The ADR template, the Hindsight field list, and the output templates earn their tokens, but the diagram-complexity blockquote ("before drawing, rate it") duplicates the diagram paragraph in Step 2, and the opener "This command ensures decisions are properly recorded" is throat-clearing. Not 5 because those pieces could be trimmed or consolidated.

4 / 5

Actionability

Concrete, fillable guidance throughout: the full ADR skeleton, the retain fields ("Title / Category / Content / Context"), and the exact embed syntax `![<concise alt>](./<adr-name>.png "<Title>")`. Not 5 because it never specifies where the ADR is saved or how to invoke the Hindsight `retain` and render-diagram tools, and the "Parse the decision" step relies on the user to supply content.

4 / 5

Workflow Clarity

Six clearly sequenced steps with explicit approval checkpoints ("Present the ADR to the user for review and approval", "Only update CLAUDE.md if the user approves") and a closing confirmation report. Not 5 because there is no feedback loop for the failure paths — no instruction to revise when the user rejects the draft ADR, nor what to do if Hindsight or the render-diagram skill is unavailable (only the diagram case has a skip condition).

4 / 5

Progressive Disclosure

A single well-organized file (blockquote / Steps / Important) with clearly signaled one-level-deep external references ("the **render-diagram** skill", `/devflow:render-diagram`), and no content that obviously belongs in a separate bundle file. Not 5 because diagram guidance is split across two places — the top blockquote and the Step 2 paragraph — rather than consolidated in one location.

4 / 5

Total

16

/

20

Passed

Description

66%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 clearly states what the skill does with several concrete actions, but it entirely lacks a "Use when..." trigger clause, which caps completeness and weakens trigger coverage. Adding explicit trigger phrases (e.g., "Use when the user makes an architectural or design decision, asks to record an ADR, or wants a decision retained for future recall") would raise both completeness and trigger term quality.

Suggestions

Add an explicit trigger clause, e.g. "Use when an architectural or design decision has been made, when the user asks to record an ADR or decision rationale, or when a decision should be retained for future recall."

Include common synonyms such as "ADR", "Architecture Decision Record", and "design decision" so the description matches the phrases users naturally say.

Mention the ADR output format ("structure it as an Architecture Decision Record") to close the specificity gap between the description and what the skill actually produces.

DimensionReasoningScore

Specificity

"record the decision and rationale, retain into Hindsight, and update CLAUDE.md if needed" lists several specific actions in a named domain. Not 5 because coverage has gaps: it omits the ADR structuring, user approval, and diagram outputs that are core to the skill.

4 / 5

Completeness

The "what" is clear ("Document an architectural decision — record the decision and rationale, retain into Hindsight"), but there is no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the rubric. Not 4 because the "when" is absent rather than merely imprecise.

3 / 5

Trigger Term Quality

"architectural decision", "rationale", "Hindsight", and "CLAUDE.md" give good keyword coverage of natural phrasing. Not 5 because common synonyms and variations users would say — "ADR", "design decision", "decision record" — are missing.

4 / 5

Distinctiveness Conflict Risk

"retain into Hindsight" and "update CLAUDE.md" anchor a mostly distinct niche around architectural decisions. Not 5 because without explicit trigger phrases it could overlap with general documentation or memory-keeping skills.

4 / 5

Total

15

/

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

relative_links

Relative link issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

AndreJorgeLopes/devflow

Path

devflow-plugin/skills/architecture-decision/SKILL.md

Revision

a9e5962

Reviewed

Table of Contents

DiscoveryImplementationValidation

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.

Claim skill