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

30%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./skills/antigravity-architecture-decision-records/SKILL.md

Quality

Content

27%

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

This skill reads more like a comprehensive ADR handbook than an actionable skill for Claude. It is extremely verbose, inlining five full template examples and extensive explanatory content that Claude doesn't need. The actual instructions are minimal (4 lines) while the bulk is reference material that should be split into separate bundle files for progressive disclosure.

Suggestions

Reduce to one primary template inline (the MADR format) and move the other 4 templates to separate bundle files (e.g., templates/lightweight.md, templates/y-statement.md) with clear references from SKILL.md.

Remove the 'Core Concepts' section entirely—Claude knows what ADRs are. Replace with a brief 2-3 line summary if any context is needed.

Expand the 4-line 'Instructions' section into a clear step-by-step workflow with explicit validation checkpoints (e.g., 'Verify all required sections are populated before presenting the ADR').

Cut the 'Best Practices' and 'Resources' sections significantly—integrate the most critical do's/don'ts as brief constraints in the instructions, and drop external URLs that Claude cannot access.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~350+ lines. Explains basic concepts Claude already knows (what an ADR is, when to write one, lifecycle states). Five full template examples with extensive prose content that could be replaced by a single template with brief annotations. The 'Core Concepts' section is entirely unnecessary for Claude.	1 / 3
Actionability	Provides concrete templates and examples that are copy-paste ready, plus real CLI commands for adr-tools. However, the skill is more of a reference document than actionable instructions—it doesn't clearly tell Claude what to do step-by-step when asked to create an ADR. The instructions section is only 4 vague lines while the bulk is templates and background.	2 / 3
Workflow Clarity	The 4-step instructions are too high-level to be a clear workflow. The review checklist provides good checkpoints but is presented as supplementary rather than integrated into the creation workflow. There's no explicit validation step (e.g., verify all required sections are filled, check for missing consequences) before finalizing an ADR.	2 / 3
Progressive Disclosure	Monolithic wall of content with no bundle files or external references for detailed templates. Five full template examples are inlined when they should be in separate files. The skill tries to be both an overview and a comprehensive reference, resulting in poor organization for a SKILL.md that should be concise with pointers to detail.	1 / 3
	Total	6 / 12 Passed

Description

32%

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 identifies a clear domain (ADRs) but relies on generic verbs and lacks explicit trigger guidance ('Use when...'). It would benefit from listing specific concrete actions and including natural user phrasings that would help Claude select this skill at the right time.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, update, or review an ADR, document an architecture decision, or maintain a decision log.'

Include more natural trigger terms users might say, such as 'decision log,' 'ADR template,' 'document a technical decision,' 'architecture decision record markdown.'

Replace generic verbs ('maintaining, managing') with specific concrete actions like 'generate ADR templates from a standard format, update decision statuses (proposed/accepted/deprecated), link superseding decisions.'

Dimension	Reasoning	Score
Specificity	Names the domain (Architecture Decision Records/ADRs) and some actions ('creating, maintaining, and managing'), but these are fairly generic verbs. It doesn't list specific concrete actions like 'generate ADR templates, update status fields, link related decisions, format markdown files.'	2 / 3
Completeness	Describes what it does (patterns for creating/maintaining ADRs) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' should cap completeness at 2, and the 'what' is also somewhat vague, so this scores a 1.	1 / 3
Trigger Term Quality	Includes 'Architecture Decision Records' and 'ADRs' which are good trigger terms, plus 'technical decisions' and 'rationale.' However, it misses common user phrasings like 'document architecture decisions,' 'ADR template,' 'decision log,' or 'record a decision.'	2 / 3
Distinctiveness Conflict Risk	ADRs are a fairly specific niche which helps distinctiveness, but the broad language around 'technical decisions' and 'managing' could overlap with general documentation or project management skills. The ADR acronym provides some distinction but without explicit triggers it's not fully clear.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: boisenoise/skills-collections
Commit: c45b103

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