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

76%

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

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.

Highly actionable content with excellent templates, tooling commands, and management guidance, but it is a monolithic file: fully worked example templates inflate token cost and material that belongs in separate reference files is inlined. Splitting templates into a references/ directory would improve both conciseness and organization.

Suggestions

Move the five full ADR templates into separate files under references/ (e.g. references/templates/madr.md) and keep only a skeleton plus a one-line pointer to each in SKILL.md, cutting the body to a fraction of its current size.

Replace fully-filled example content that restates well-known technology trade-offs (PostgreSQL vs MySQL vs MongoDB pros/cons) with placeholder-style skeletons, since Claude can generate that domain content itself.

Add an explicit validation feedback loop to the ADR workflow, e.g. after PR review feedback: revise the ADR and re-run the review checklist before acceptance.

Dimension	Reasoning	Score
Conciseness	The five fully-filled worked templates (~250 lines) include content Claude already knows, e.g. the PostgreSQL example's detailed pros/cons ("ACID compliant, excellent JSON support (JSONB)... no built-in full-text search"); skeleton templates would convey the format as effectively with far fewer tokens.	3 / 5
Actionability	Provides complete copy-paste markdown templates for five ADR formats, executable adr-tools commands ("adr init docs/adr", "adr new -s 3 ..."), a concrete directory structure, and review checklists covering the common cases.	5 / 5
Workflow Clarity	"Creating a New ADR" gives a clear 4-step sequence (copy template.md, fill, submit PR, update index) and the review checklist adds before/during/after checkpoints, but there is no explicit validate-and-retry feedback loop, so it falls short of the top anchor.	4 / 5
Progressive Disclosure	No bundle files exist; all five full templates, the index README, and the review checklist are inlined in a single ~450-line SKILL.md when the templates clearly belong in separate reference files. Section headers provide real structure, keeping this above the minimal-structure anchor, but content that should be separate is inline.	3 / 5
	Total	15 / 20 Passed

Description

82%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 the skill does and when to use it with concrete trigger phrases and a distinctive niche. The only weaknesses are the generic "following best practices" filler and slightly thin coverage of natural synonym variations.

Dimension	Reasoning	Score
Specificity	"Write and maintain Architecture Decision Records (ADRs)" names the domain and two concrete actions, but "following best practices" is generic filler and no further specific actions are enumerated, matching the 1-2-concrete-actions anchor rather than the several-actions anchor.	3 / 5
Completeness	The what ("Write and maintain Architecture Decision Records (ADRs)") and the when ("Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes") are both explicitly and concretely stated, matching the top anchor.	5 / 5
Trigger Term Quality	Natural phrases like "documenting significant technical decisions", "reviewing past architectural choices", and the ADR abbreviation give good keyword coverage, but common variations such as "design decisions", "decision log", or "record this decision" are missing.	4 / 5
Distinctiveness Conflict Risk	ADR documentation is a clear niche with distinct triggers (architecture decision, decision record, ADR) and minimal overlap with generic documentation or writing skills.	5 / 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: Dicklesworthstone/pi_agent_rust
Path: tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/architecture-decision-records/SKILL.md
Commit: 38d4f88

Reviewed: 28 minutes 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.