adr

Generate Architecture Decision Records that capture the reasoning behind technical decisions. Use when the user asks to "create an ADR", "document a decision", "record why we chose X", or discusses architectural trade-offs worth preserving.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Failed to scan

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./skills/adr/SKILL.md

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.

A clean, well-structured, instruction-only skill with a complete template and clear workflow. It scores consistently high; the main gap is the absence of an explicit validation/verification step after generating the ADR.

Suggestions

Add an explicit validation step to the workflow, e.g. confirm the ADR number does not collide with existing files and that each section is non-empty before writing.

Tighten the template placeholder prose (e.g. 'Context: 2-4 sentences describing the motivating issue') to reduce token usage further.

Dimension	Reasoning	Score
Conciseness	The body is lean with a copy-paste template and terse instructions, assuming Claude's competence without explaining what an ADR is; minor instances like the template placeholder prose could be trimmed, fitting the efficient-with-minor-trim anchor.	4 / 5
Actionability	It provides a complete markdown ADR template plus concrete guidance on file locations (docs/adr/, adr/), numbering, and per-section length targets, giving mostly executable guidance with only minor gaps for an instruction-only skill.	4 / 5
Workflow Clarity	A clear numbered sequence (extract, locate, number, write, capture the why) is present with the location-check acting as a checkpoint; no explicit validation step exists, but ADR creation is non-destructive so the validation cap does not apply, fitting the clear-sequence-with-minor-validation-gaps anchor.	4 / 5
Progressive Disclosure	The body is well-organized into ADR Format, Instructions, and See Also with no nested references, and the single-file template is appropriately self-contained; it is not under 50 lines and the See Also links point to sibling skills rather than progressively disclosing this skill's own detail, so it sits at good-structure rather than the top anchor.	4 / 5
	Total	16 / 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, well-structured description that clearly states what the skill does and when to use it, with natural trigger phrases. It is slightly light on enumerating multiple concrete actions and could add a few more trigger synonyms.

Suggestions

List a second concrete action beyond 'generate' (e.g., 'number and file ADRs in docs/adr/') to lift specificity.

Add one or two more natural trigger variations like 'decision log' or 'ADR template' to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	The description names the domain and the concrete action 'Generate Architecture Decision Records that capture the reasoning behind technical decisions', but beyond the single core action there is little additional action coverage, matching the anchor for naming a domain with 1-2 concrete actions.	3 / 5
Completeness	It explicitly answers both 'what' (generate ADRs capturing reasoning) and 'when' with concrete trigger phrases in a 'Use when...' clause, matching the anchor for clearly and explicitly answering both with concrete triggers.	5 / 5
Trigger Term Quality	It includes several natural user phrases ('create an ADR', 'document a decision', 'record why we chose X', 'architectural trade-offs worth preserving'), giving good keyword coverage, though a few synonyms like 'ADR template' or 'decision log' are absent.	4 / 5
Distinctiveness Conflict Risk	'Architecture Decision Records' is a clear niche with distinct triggers, but the topic has minor overlap with adjacent research/review skills, fitting the anchor for mostly distinct skills with minor overlap risk.	4 / 5
	Total	16 / 20 Passed

Validation

100%

Warnings & errors only

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: tslateman/duet
Path: skills/adr/SKILL.md
Commit: 5647baf

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.