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

65%

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 ./skills/architecture-decision-records/SKILL.md

Quality

Content

46%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.

The content is information-rich and actionable for ADR management, but it is padded with full sample documents and lacks progressive disclosure, with no bundle files splitting out the template gallery. The authoring workflow also needs explicit validation checkpoints.

Suggestions

Move the five full example ADRs into a single references/templates.md file and keep one lean canonical template inline in SKILL.md, linking out for the rest.

Add explicit validation checkpoints to the 'Instructions' workflow (e.g., verify Status is set, confirm Related ADRs links resolve, re-validate index after superseding) to lift workflow clarity above the batch/destructive cap.

Trim prose explanations of ADR fundamentals (the 'What is an ADR' section) since Claude already knows this, keeping only team-specific conventions.

Dimension	Reasoning	Score
Conciseness	The body inlines five fully written-out sample ADRs (e.g., the ~95-line PostgreSQL example and ~70-line RFC), which is substantial padding of finished documents Claude already knows how to produce; noticeably verbose even though the structural sections are efficient.	2 / 5
Actionability	Provides concrete, copy-paste-ready management commands (`adr init`, `adr new -s 3`, `brew install adr-tools`), an explicit directory structure, an index format, and worked example ADRs, with only minor gaps on the authoring side.	4 / 5
Workflow Clarity	The core 'Instructions' workflow is a high-level 4-step list without validation checkpoints, and supersede/deprecate operations lack explicit verify steps; the Review Process checklists help but the destructive/batch cap holds this at 3.	3 / 5
Progressive Disclosure	A single monolithic SKILL.md inlines five full templates and complete sample ADRs that clearly belong in separate reference files; section headers and external links exist, but bulk content is not split out.	2 / 5
	Total	11 / 20 Passed

Description

83%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.

The description is strong: third-person, concrete, and explicitly pairs a clear 'what' with an explicit 'Use when...' trigger clause. Minor room to add a few more natural synonyms, but it capably distinguishes the skill.

Dimension	Reasoning	Score
Specificity	Names the domain plus several concrete actions ("Write and maintain Architecture Decision Records", "following best practices for technical decision documentation"), with only minor generic gaps, fitting the 'lists several specific actions' anchor.	4 / 5
Completeness	Explicitly answers both what ("Write and maintain Architecture Decision Records...") and when ("Use when documenting... reviewing... or establishing...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ("documenting significant technical decisions", "reviewing past architectural choices", "establishing decision processes") with good coverage, though a few synonyms like bare "architecture decisions" are absent.	4 / 5
Distinctiveness Conflict Risk	Targets a distinct named practice (ADRs) with niche-specific triggers, carrying only minor overlap risk with general documentation skills.	4 / 5
	Total	17 / 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: 4 missing	Warning

	Total	15 / 16 Passed

Repository: rmyndharis/antigravity-skills
Path: skills/architecture-decision-records/SKILL.md
Commit: 3eff4af

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.