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

70%

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

71%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 skill is highly actionable with executable commands and copy-paste templates and a clear review workflow, but it is verbose and inlines large template material that would benefit from progressive disclosure into reference files.

Suggestions

Move the five full ADR templates into a separate templates/ reference file and keep only one compact example inline in SKILL.md.

Tighten the inlined worked examples (e.g., trim the PostgreSQL pros/cons detail) to reduce token load.

Add an explicit validation/verification step in the Instructions (e.g., run the review checklist before marking an ADR Accepted) to reach a 5 on workflow clarity.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and avoids explaining concepts Claude already knows, but it inlines five full worked templates (~400 lines) that could be tightened or moved to separate files, leaving it padded rather than lean.	3 / 5
Actionability	Provides copy-paste-ready ADR templates and concrete, executable adr-tools commands ("brew install adr-tools", "adr init", "adr new -s 3") covering the common cases fully.	5 / 5
Workflow Clarity	A clear sequenced Instructions list plus an ADR Review Checklist with Before/During/After checkpoints gives a strong sequence; minor validation gaps keep it just below a 5.	4 / 5
Progressive Disclosure	Good section structure exists, but all five templates and management/review material are inlined in SKILL.md with no signaled one-level-deep references to separate files, so content that should be split is inline.	3 / 5
	Total	15 / 20 Passed

Description

70%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 clearly conveys what the skill does and targets a distinct, well-scoped niche, but it omits an explicit "Use when..." trigger clause, which caps completeness. Specificity and trigger-term quality are strong.

Suggestions

Add an explicit trigger clause, e.g. "Use when making significant architectural decisions, choosing technologies, or onboarding team members to past decisions."

Consider adding user-natural phrasings like "decision records" or "technical decision logs" to broaden trigger coverage.

Trim the opening "Comprehensive patterns" framing slightly to lead with the concrete actions.

Dimension	Reasoning	Score
Specificity	Names the ADR domain and several concrete actions — "creating, maintaining, and managing" — with "capture the context and rationale behind significant technical decisions", listing multiple specific actions with only minor coverage gaps.	4 / 5
Completeness	Has a clear "what" (comprehensive patterns for creating/maintaining/managing ADRs) but no explicit "Use when..." trigger clause, so per the cap guideline completeness cannot exceed 3.	3 / 5
Trigger Term Quality	Includes natural terms a user would say ("Architecture Decision Records", "ADRs", "technical decisions") with good keyword coverage, though a few common synonyms or phrasings are missing.	4 / 5
Distinctiveness Conflict Risk	"Architecture Decision Records (ADRs)" is a clear, well-defined niche with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	16 / 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: sickn33/antigravity-awesome-skills
Path: skills/architecture-decision-records/SKILL.md
Commit: 1f67c44

Reviewed: about 16 hours 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.