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 ./skills/architecture-decision/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 skill body is a tight, highly actionable workflow: a complete ADR template, concrete retain fields, user-approval checkpoints, and a confirmation block. Only minor gaps remain — a missing verification of the Hindsight retain and slight redundancy in the diagram guidance.

DimensionReasoningScore

Conciseness

The body is efficient — a copy-paste ADR template, terse retain-field list, and confirmation block with no padding about what ADRs are. Minor trimmable parts exist: 'Be honest about tradeoffs. Every decision has downsides.' and the diagram guidance appearing twice (the complexity-rating blockquote and the step-2 paragraph) are slight over-explanation, matching the score-4 anchor rather than the lean 5.

4 / 5

Actionability

Fully actionable throughout: a complete fill-in ADR template, an exact checklist of Hindsight retain fields (Title/Category/Content/Context), the conditional CLAUDE.md update procedure, and a copy-paste-ready confirmation output block. This matches the score-5 anchor of copy-paste-ready material covering the common cases; as an instruction-only skill, absence of code is not penalized.

5 / 5

Workflow Clarity

Six steps are clearly sequenced with explicit checkpoints: ask for elaboration when arguments are brief (step 1), user review and approval before proceeding (step 3), and 'Only update CLAUDE.md if the user approves' (step 5). Not a 5 because there is no verification that the Hindsight retain actually succeeded before reporting 'Retained to Hindsight: Yes' in step 6 — a minor validation gap per the score-4 anchor.

4 / 5

Progressive Disclosure

No bundle files exist and none are needed for this single-purpose command; sections (Steps, Important) are well organized and the ADR template is appropriately inline. Score 4 rather than 5 because the diagram guidance is split between the top blockquote and step 2 with slightly redundant framing, leaving minor organization gaps.

4 / 5

Total

17

/

20

Passed

Description

58%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 concrete, specific actions, but it lacks any 'when to use' trigger guidance and misses the natural synonym 'ADR'. It is specific and distinct but under-serves discoverability.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user makes or asks to record an architectural decision, or mentions ADRs, design decisions, or tradeoffs.'

Include the standard synonyms 'ADR' and 'Architecture Decision Record' in the description so it matches the most common terms users and Claude would say.

Trim the redundancy between 'Document an architectural decision' and 'record the decision and rationale' to tighten the what-clause.

DimensionReasoningScore

Specificity

Names the domain ("architectural decision") and several concrete actions — "record the decision and rationale, retain into Hindsight, and update CLAUDE.md" — matching the score-4 anchor of several specific actions with minor coverage gaps. Not a 5 because "Document an architectural decision" and "record the decision and rationale" are partially redundant, so the effective action list is narrower than comprehensive.

4 / 5

Completeness

The 'what' is clear (document, retain into Hindsight, update CLAUDE.md), but there is no 'Use when...' clause or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 3. Not a 4 because the 'when' is only weakly implied by the phrase 'architectural decision', never stated.

3 / 5

Trigger Term Quality

Relevant keywords exist ("architectural decision", "decision", "rationale", "CLAUDE.md") but common variations are missing — most notably "ADR" / "Architecture Decision Record", the standard term a user or Claude would naturally use. Matches the score-3 anchor of relevant keywords missing synonyms; a 4 would require coverage like 'decision, ADR, architecture, tradeoffs'.

3 / 5

Distinctiveness Conflict Risk

The niche is fairly distinct — 'architectural decision' retention into 'Hindsight' and CLAUDE.md updates is unlikely to fire for unrelated skills, matching the score-4 anchor of mostly distinct with minor overlap risk. Not a 5 because without explicit trigger phrases it could overlap with generic documentation or note-taking skills.

4 / 5

Total

14

/

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

skills/architecture-decision/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.