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

52%

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

Fix and improve this skill with Tessl

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

Quality

Content

14%

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

This skill is essentially a table of contents with no substantive content in the main file. The instructions are too vague to be actionable, and the 27 sub-skill references appear to be a broken decomposition of what should have been inline templates and examples — with duplicate links, confusingly named fragments (e.g., individual database options as separate 'skills'), and no bundle files to back them up. The skill fails to provide any concrete, executable guidance for writing ADRs.

Suggestions

Include at least one complete ADR template directly in the SKILL.md with filled-in example content, rather than deferring everything to sub-files.

Consolidate the 27 sub-skills into 3-5 meaningful references (e.g., templates.md, examples.md, lifecycle.md) and fix duplicate/confusing names like 'Positive' and 'Negative'.

Add a concrete workflow with validation steps, e.g., '1. Create file docs/adr/NNNN-title.md using template below → 2. Fill all required sections → 3. Verify: check that Context, Options, and Decision sections are non-empty → 4. Submit for review'.

Remove the 'Use this skill when / Do not use this skill when' sections or compress them to a single sentence — Claude can infer when ADRs are appropriate from the skill description.

Dimension	Reasoning	Score
Conciseness	The 'Use this skill when' and 'Do not use this skill when' sections explain things Claude already understands. The instructions section is reasonably brief but the overall file is padded with organizational boilerplate rather than substantive content.	2 / 3
Actionability	The main SKILL.md contains no concrete examples, no templates, no executable commands, and no copy-paste ready content. The four-step instructions are vague ('Capture the decision context') with no specifics. All actionable content is deferred to 27 sub-skill files that are not provided.	1 / 3
Workflow Clarity	The four numbered instructions are extremely high-level with no validation checkpoints, no feedback loops, and no concrete sequencing. There is no guidance on what constitutes a complete or valid ADR, and no verification steps.	1 / 3
Progressive Disclosure	The 27 sub-skill references are poorly organized and confusingly named — items like 'Positive', 'Negative', 'Risks', and database options (PostgreSQL, MySQL, MongoDB) appear to be fragments of an example ADR that were incorrectly split into separate sub-skills. There are duplicate filenames (e.g., two 'Positive' and two 'Negative' links pointing to the same file). No bundle files are provided to verify these references exist, and the structure suggests a broken decomposition rather than intentional progressive disclosure.	1 / 3
	Total	5 / 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 solid skill description with clear 'what' and 'when' clauses, strong trigger terms specific to the ADR domain, and low conflict risk. The main weakness is that the capability description could be more specific about the concrete actions performed (e.g., creating ADR templates, numbering/linking decisions, tracking superseded records).

Suggestions

Add more specific concrete actions like 'create ADR templates, track decision status (proposed/accepted/deprecated/superseded), link related decisions' to improve specificity.

Dimension	Reasoning	Score
Specificity	Names the domain (ADRs) and some actions ('write and maintain', 'documenting', 'reviewing', 'establishing decision processes'), but doesn't list specific concrete actions like creating templates, linking decisions, tracking status changes, or specific ADR format elements.	2 / 3
Completeness	Clearly answers both 'what' (write and maintain ADRs following best practices) and 'when' (explicit 'Use when' clause covering documenting decisions, reviewing past choices, or establishing processes).	3 / 3
Trigger Term Quality	Includes strong natural trigger terms: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes'. These cover the main ways users would refer to this topic.	3 / 3
Distinctiveness Conflict Risk	ADRs are a very specific niche within technical documentation. The triggers are distinct and unlikely to conflict with general documentation or coding skills. Terms like 'Architecture Decision Records' and 'ADRs' are highly specific.	3 / 3
	Total	11 / 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: Dokhacgiakhoa/antigravity-ide
Path: .agent/skills/architecture-decision-records/SKILL.md
Commit: c4a059b

Reviewed: 1 day 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.