architecture-decision-records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is highly actionable with concrete templates and executable adr-tools commands, but it is verbose and monolithic, packing five full templates and explanatory background into one file without progressive disclosure.

Suggestions

Move the full ADR templates into a separate references file (e.g., references/templates.md) and keep SKILL.md as a concise overview with clearly-signaled one-level links.

Tighten the 'What is an ADR' and lifecycle sections to remove concepts Claude already knows, or compress into a brief reference.

Add explicit validation checkpoints to the Instructions (e.g., 'Confirm all viable options and pros/cons are documented before recording the decision').

Dimension	Reasoning	Score
Conciseness	The body is lengthy with five fully-rendered templates plus 'What is an ADR' and lifecycle content Claude largely already knows; while mostly relevant, it could be tightened significantly by summarizing templates rather than rendering them in full.	2 / 3
Actionability	Provides copy-paste-ready templates (MADR, lightweight, Y-statement, RFC, deprecation) and concrete executable commands ('brew install adr-tools', 'adr init', 'adr new -s 3', 'adr generate toc'), plus an explicit directory structure and checklists.	3 / 3
Workflow Clarity	Sequencing exists (4-step Instructions, lifecycle diagram, phased migration plan, before/during/after review checklist), but the core Instructions are abstract and lack explicit validation checkpoints or a validate-fix-retry loop.	2 / 3
Progressive Disclosure	It is a single monolithic SKILL.md with no bundle files in references/scripts/assets; the five full templates and reference material are all inline and could be split into separate, clearly-signaled files.	2 / 3
	Total	9 / 12 Passed

Description

50%

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 identifies the domain and core actions but is generic and lacks an explicit 'Use when' trigger clause. It is serviceable but would benefit from concrete trigger terms and a tighter capability list.

Suggestions

Add an explicit 'Use when ...' trigger clause listing situations users would naturally name (e.g., 'Use when recording architectural decisions, choosing between technologies, or onboarding teams to past design trade-offs').

Replace generic phrasing like 'comprehensive patterns' with a concise list of concrete actions (e.g., 'Draft, review, supersede, and index ADRs').

Add common trigger variations users might say ('architecture decision', 'design trade-off', 'record a decision', 'ADR template').

Dimension	Reasoning	Score
Specificity	Names the ADR domain and several actions ('creating, maintaining, and managing ... capture the context and rationale') but leans on generic phrasing like 'comprehensive patterns' rather than enumerating comprehensive concrete actions.	2 / 3
Completeness	Clearly answers 'what' the skill does, but the 'when' is only implied via 'significant technical decisions' with no explicit trigger clause, which caps completeness at 2 per the rubric.	2 / 3
Trigger Term Quality	Includes relevant natural terms ('Architecture Decision Records', 'ADRs', 'technical decisions') but lacks common trigger phrasings and any 'Use when' guidance, missing common variations users might say.	2 / 3
Distinctiveness Conflict Risk	ADRs are a fairly distinct niche, but 'comprehensive patterns ... significant technical decisions' is broad enough to overlap with general architecture or documentation skills.	2 / 3
	Total	8 / 12 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: boisenoise/skills-collections
Commit: f36337d

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