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.

1.45x

Quality

79%

Does it follow best practices?

Impact

99%

1.45x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/documentation-generation/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.

A highly actionable, well-organized ADR skill whose main weakness is token weight: five complete worked-example ADRs and all supporting material live in a single monolithic SKILL.md with no progressive disclosure to reference files.

Suggestions

Move the four secondary templates (lightweight, Y-statement, deprecation, RFC) into a references/ file such as TEMPLATES.md and keep only the standard MADR template inline, linking to the rest.

Shorten the worked PostgreSQL example to template structure plus a condensed illustration, or move the full example to references/examples.md to reduce inline token cost.

Split the adr-tools automation commands and review checklist into a references/management.md so SKILL.md reads as an overview pointing to detailed material.

Dimension	Reasoning	Score
Conciseness	Mostly useful content that avoids over-explaining basic concepts, but five fully fleshed-out example ADRs (the MADR PostgreSQL example alone runs ~90 lines) are heavy and overlap; they could be trimmed to template structure plus one short worked example.	3 / 5
Actionability	Provides copy-paste-ready markdown templates, executable adr-tools commands (brew install, adr init, adr new -s 3, adr generate toc), a concrete directory layout, and review checklists covering the common cases.	5 / 5
Workflow Clarity	Clear sequences for the ADR lifecycle, creating a new ADR, and a phased migration plan with validation ("validate consistency", "monitor"), plus a before/during/after review checklist serving as checkpoints; minor feedback-loop gaps keep it short of the top anchor.	4 / 5
Progressive Disclosure	Well-sectioned with clear headers, but with no bundle files the entire 440-line body — all five templates, directory structures, and checklists — is inlined in one monolithic file rather than split into one-level-deep references.	3 / 5
	Total	15 / 20 Passed

Description

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

A strong, well-structured description that clearly states capability and trigger conditions in third-person imperative voice with concrete examples. Minor tightening of the generic "best practices" phrasing would push specificity and trigger coverage to the top anchor.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ("Write and maintain Architecture Decision Records", "documenting significant technical decisions", "reviewing past architectural choices", "establishing decision processes"), but "following best practices for technical decision documentation" is generic filler that keeps it just short of comprehensive.	4 / 5
Completeness	Explicitly answers both what ("Write and maintain Architecture Decision Records (ADRs) following best practices...") and when ("Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good coverage of natural terms users would say — "Architecture Decision Records", the synonym "ADRs", "technical decisions", "architectural choices", and "decision processes" — though a few common phrasings are absent.	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	18 / 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: wshobson/agents
Path: plugins/documentation-generation/skills/architecture-decision-records/SKILL.md
Commit: d6837ae

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