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.61x

Quality

75%

Does it follow best practices?

Impact

100%

1.61x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/architecture-decision-records/SKILL.md

The canonical home for this skill is architecture-decision-records in wshobson/agents

Quality

Content

63%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 thorough, well-structured ADR skill with concrete templates, commands, and review checklists. Its main weakness is length: fully populated example templates and introductory concept explanations inflate the body, and the lack of any reference files leaves content inline that would benefit from progressive disclosure.

Suggestions

Move the five filled-in ADR templates into separate reference files (e.g., references/templates/) and keep SKILL.md as an overview with one-line pointers, reducing the inline bulk.

Trim the 'What is an ADR?' section and replace fully worked examples (like the PostgreSQL ADR) with skeleton templates, since Claude already understands the underlying concepts.

Replace the generic 'following best practices' framing with the specific concrete actions the skill actually performs.

Dimension	Reasoning	Score
Conciseness	The ~445-line body inlines five fully filled ADR templates (e.g., the detailed PostgreSQL example) and a 'What is an ADR?' section that explains concepts Claude already knows; mostly useful but noticeably padded and could be tightened.	3 / 5
Actionability	Provides five copy-paste-ready template formats, a concrete directory layout, executable adr-tools bash commands, and review checklists — concrete and actionable with only minor gaps.	4 / 5
Workflow Clarity	Sequenced lifecycle, a 'Creating a New ADR' step list, and Before/During/After review checklists supply clear checkpoints and feedback loops; the supersede workflow is explicitly framed as 'don't edit accepted ADRs, write new ones'.	4 / 5
Progressive Disclosure	Well-organized with clear section headers, but no bundle files exist and all five detailed templates are inlined in SKILL.md when much of this reference material would be better split into separate template files one level deep.	3 / 5
	Total	14 / 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 description that clearly answers both 'what' and 'when' in third-person voice with concrete trigger phrases and a distinct niche. Minor room for improvement in keyword synonyms and replacing the generic 'best practices' phrasing.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions — 'Write and maintain', 'documenting', 'reviewing', 'establishing' — but 'following best practices' is slightly generic, leaving minor coverage gaps versus a fully comprehensive list.	4 / 5
Completeness	Explicitly states both what it does ('Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation') and when to use it ('Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes').	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('documenting significant technical decisions', 'reviewing past architectural choices') and the 'ADR' acronym, though common synonyms like 'decision log' or 'tech choices' are missing.	4 / 5
Distinctiveness Conflict Risk	ADRs are a clear, well-defined niche with distinct triggers; minimal overlap risk with other skills since the domain and use cases are specific.	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: Dicklesworthstone/pi_agent_rust
Path: tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/architecture-decision-records/SKILL.md
Commit: 6453c0b

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