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

—

Does it follow best practices?

Impact

99%

1.45x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

77%

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

The body is well-organized and highly actionable with concrete templates, commands, and checklists, but it is monolithic and verbose — five fully worked templates and basic concept explanations inline in a single file. Splitting templates into reference files and trimming beginner exposition would improve token efficiency and progressive disclosure.

Suggestions

Move the five full ADR templates into separate reference files (e.g. references/templates/) and summarize them in SKILL.md with one-line descriptions plus links, reducing the inline wall of text.

Trim or remove the 'What is an ADR?' basics and condense the MADR worked example, which restates context/decision/consequences Claude already understands.

Keep the adr-tools commands and review checklists (the strongest, most actionable parts) prominent near the top so the core workflow is discoverable before the long template examples.

Dimension	Reasoning	Score
Conciseness	The ~440-line body pads five fully worked templates and a 'What is an ADR?' section that restates basics Claude already knows; not a 3 because much could be tightened, and not a 1 because nearly all content is on-topic ADR guidance rather than off-topic fluff.	2 / 3
Actionability	Provides copy-paste-ready markdown templates, executable adr-tools commands (e.g. "adr init docs/adr", "adr new -s 3 ..."), a concrete directory layout, and checklists; not a 2 because the guidance is concrete and executable rather than abstract.	3 / 3
Workflow Clarity	Multi-step flows are clearly sequenced (numbered 'Creating a New ADR', phased migration plan) with explicit review checklists covering before/during/after; not a 2 because validation checkpoints are present via checklists, and ADR authorship is non-destructive so no missing feedback loop is penalized.	3 / 3
Progressive Disclosure	No bundle files exist and everything lives inline in one ~440-line file, including five full templates that read like content that should be split; not a 1 because sections are well-organized, and not a 3 because the simple-skill (<50 lines) exception does not apply and no one-level-deep references are signaled.	2 / 3
	Total	10 / 12 Passed

Description

100%

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: it uses third-person/active voice, states concrete actions, and pairs a clear 'what' with an explicit 'Use when' trigger clause covering natural user phrasings. It is concise, on-niche, and low conflict risk.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions — "Write and maintain Architecture Decision Records (ADRs)" — applied to a specific artifact, matching the 'lists multiple specific concrete actions' anchor; not a 2 because the verbs are concrete and tied to a concrete noun rather than a vague domain.	3 / 3
Completeness	Clearly answers both what ("Write and maintain ADRs") and when with an explicit "Use when..." clause listing triggers; not a 2 because the when is explicit rather than merely implied.	3 / 3
Trigger Term Quality	Triggers like "documenting significant technical decisions", "reviewing past architectural choices", and "establishing decision processes" are natural phrases a user would say, with strong coverage; not a 2 because common variations (technical decisions, architectural choices, ADRs) are all present.	3 / 3
Distinctiveness Conflict Risk	ADRs are a distinct niche with specific triggers unlikely to collide with other skills; not a 2 because the domain and triggers are narrowly scoped rather than overlapping with general documentation skills.	3 / 3
	Total	12 / 12 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
Commit: 5cc2549

Reviewed: 9 days 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.