spec-loop-write-adr

Create, update, or supersede architecture decision records under `architecture-decisions/`. Use when the user asks for ADR work or a Spec Loop workflow routes ADR writing.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

90%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 well-structured, concise instruction skill with concrete classification guidance and a clear clarification gate. Adding an explicit ADR output-validation step and ensuring referenced files are bundled would push it to full marks.

Suggestions

Add an explicit validate/review checkpoint after drafting the ADR (e.g. verify section taxonomy is correctly applied and the Decision TL;DR is present) before considering the ADR complete.

Bundle the referenced adr-format.md (or a stub) so the one-level-deep reference actually resolves, improving navigation for progressive_disclosure.

Number the core workflow steps (read adr-format -> run clarification gate -> classify inputs -> draft -> validate) so the sequence is an explicit ordered checklist rather than prose.

Dimension	Reasoning	Score
Conciseness	The body is lean and instruction-only with no padding and no explanation of concepts Claude already knows; every line carries actionable guidance.	5 / 5
Actionability	It gives concrete, specific guidance: an explicit section taxonomy with definitions ("`Context` = pre-decision facts…", "`Analysis` = the clarified reasoning…"), a named handoff target, and an unambiguous gating rule — fully actionable for an instruction skill.	5 / 5
Workflow Clarity	A clear sequence exists (read adr-format, run the clarification gate, classify inputs, draft sections) with a re-run checkpoint ("Re-run this gate whenever later ADR drafting exposes a new important open decision"), but there is no explicit output-validation step on the drafted ADR itself, a minor gap for a document-manipulation skill.	4 / 5
Progressive Disclosure	The body is well-organized with clear sectioning and one-level-deep references (adr-format.md, the clarify-task skill), but the referenced adr-format.md is not actually present in the bundle, a minor navigation gap.	4 / 5
	Total	18 / 20 Passed

Description

92%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, focused description that clearly states both capability and trigger conditions with concrete verbs and a specific location. Minor room to add common synonym triggers like "ADRs" or "decision log".

Dimension	Reasoning	Score
Specificity	"Create, update, or supersede architecture decision records" lists three concrete lifecycle actions plus a concrete location ("under `architecture-decisions/`"), giving comprehensive coverage of this narrow domain.	5 / 5
Completeness	It explicitly answers both what ("Create, update, or supersede architecture decision records") and when ("Use when the user asks for ADR work or a Spec Loop workflow routes ADR writing") with concrete trigger phrases.	5 / 5
Trigger Term Quality	"ADR work", "Spec Loop workflow", and "architecture decision records" are relevant natural phrases, but common synonyms a user might say ("ADRs", "decision log", "architecture decisions") are not all covered.	4 / 5
Distinctiveness Conflict Risk	It targets a clear niche (ADRs under a specific path) tied to a specific workflow (Spec Loop), leaving minimal conflict risk with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing, 1 suspicious	Warning

	Total	15 / 16 Passed

Repository: dpolivaev/spec-loop
Path: skills/spec-loop-write-adr/SKILL.md
Commit: 7033338

Reviewed: 6 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.