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

—

Does it follow best practices?

Impact

100%

1.61x

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.

Highly actionable content with executable tooling commands, copy-paste templates, and clear review-gated workflows. Its main weaknesses are verbosity from over-explained concepts and fully narrated examples, and a monolithic single-file structure that should offload templates to reference files.

Suggestions

Trim concept explanations Claude already knows (the 'What is an ADR?' definition and lifecycle section) and convert the five fully narrated template examples into lean skeleton templates, keeping one short worked example.

Move the template formats (MADR, lightweight, Y-statement, deprecation, RFC) and the review checklist into separate files under references/ (e.g. references/templates.md, references/review-checklist.md), leaving SKILL.md as a concise overview that links one level deep.

Drop or relocate the hypothetical internal paths (e.g. '/docs/benchmarks/database-comparison.md') that are not real bundle files, since they cannot be navigated.

Dimension	Reasoning	Score
Conciseness	The ~440-line body explains concepts Claude already knows ('What is an ADR?', lifecycle, when-to-write tables) and includes five fully narrated template examples with fictional rationale; useful but padded and could be tightened to template skeletons.	2 / 3
Actionability	Provides copy-paste-ready markdown templates, executable adr-tools commands (brew install, adr init/new/generate/link), a concrete directory layout, and review checklists — concrete and directly executable.	3 / 3
Workflow Clarity	Clear sequences (ADR creation steps gated on PR review/approval, migration phases, lifecycle) plus explicit before/during/after review checklists that act as validation checkpoints.	3 / 3
Progressive Disclosure	Well-organized with headers, but everything is inline in one ~440-line file with no bundle files; the five templates and worked examples are content that should be split into separate reference files rather than crammed into SKILL.md.	2 / 3
	Total	10 / 12 Passed

Description

90%

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, third-person description that clearly states both capability and explicit use triggers with good natural keyword coverage. The only weakness is slightly generic action verbs ('Write and maintain') paired with 'best practices' filler.

Dimension	Reasoning	Score
Specificity	Names the domain (ADRs) and two actions ('Write and maintain') but the verbs are high-level and 'following best practices' is generic filler, so it is not the comprehensive list of concrete actions expected at 3.	2 / 3
Completeness	Clearly answers what ('Write and maintain Architecture Decision Records...') and when ('Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes') with an explicit 'Use when' trigger clause.	3 / 3
Trigger Term Quality	'documenting significant technical decisions', 'reviewing past architectural choices', and 'establishing decision processes' plus the 'ADR' keyword give good coverage of natural terms users would say when they need this skill.	3 / 3
Distinctiveness Conflict Risk	The ADR niche is distinct and the triggers are specific to architectural decision documentation, making it unlikely to fire for an unrelated skill.	3 / 3
	Total	11 / 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: Dicklesworthstone/pi_agent_rust
Commit: e9f9b67

Reviewed: 4 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.