architecture-decision-records

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

Quality

80%

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 ./docs/v19.7/configuration/agent/skills_external/antigravity-awesome-skills-main/skills/architecture-decision-records/SKILL.md

Quality

Content

70%

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

The skill provides excellent actionable content with complete, copy-paste ready templates and clear workflows. However, it suffers from poor progressive disclosure - all content is crammed into one large file rather than being appropriately split. The verbosity could be reduced by assuming Claude understands basic ADR concepts and moving detailed templates to referenced files.

Suggestions

Move the 5 detailed templates to a separate TEMPLATES.md file and reference it from the main skill

Remove the 'What is an ADR?' section - Claude already knows this concept

Condense the 'Use this skill when' and 'Do not use this skill when' sections into a brief table

Add a quick-start section at the top with just one minimal template, then reference the full templates file for comprehensive options

Dimension	Reasoning	Score
Conciseness	The skill is comprehensive but verbose. It includes 5 full templates with extensive examples that could be condensed or moved to separate files. The core concepts section explains what an ADR is, which Claude likely already knows.	2 / 3
Actionability	Provides fully executable templates with complete markdown examples, concrete directory structures, actual CLI commands for adr-tools, and copy-paste ready content. The templates are immediately usable.	3 / 3
Workflow Clarity	Clear lifecycle diagram (Proposed → Accepted → Deprecated → Superseded), explicit review checklist with before/during/after phases, and the deprecation template includes a phased migration plan with validation steps.	3 / 3
Progressive Disclosure	This is a monolithic wall of text with all 5 templates inline. The content would benefit greatly from splitting templates into separate files (e.g., TEMPLATES.md) and keeping SKILL.md as a concise overview with references.	1 / 3
	Total	9 / 12 Passed

Description

89%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a well-structured description with explicit 'Use when' triggers and good keyword coverage for the ADR domain. The main weakness is that the capabilities could be more specific about concrete actions (e.g., 'create ADR templates', 'number and link decisions', 'track superseded records'). Overall, it effectively communicates when Claude should select this skill.

Suggestions

Add more specific concrete actions like 'create ADR templates, track decision status, link related decisions, manage superseded records' to improve specificity

Dimension	Reasoning	Score
Specificity	Names the domain (ADRs) and some actions ('Write and maintain', 'documenting', 'reviewing', 'establishing'), but doesn't list comprehensive concrete actions like specific ADR components, templates, or operations.	2 / 3
Completeness	Clearly answers both what ('Write and maintain Architecture Decision Records following best practices') and when ('Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes').	3 / 3
Trigger Term Quality	Includes strong natural keywords users would say: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes'.	3 / 3
Distinctiveness Conflict Risk	ADRs are a specific documentation format with clear niche; unlikely to conflict with general documentation or code skills due to explicit 'Architecture Decision Records' and 'ADRs' terminology.	3 / 3
	Total	11 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: duclm1x1/Dive-Ai
Commit: 20ba150

Reviewed: 5 months 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.