Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
63
Quality
55%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/architecture-decision-records/SKILL.mdQuality
Discovery
32%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 identifies a clear domain (ADRs) and mentions general actions, but lacks the explicit trigger guidance needed for Claude to know when to select this skill. It would benefit from concrete action examples and a 'Use when...' clause with natural user phrases.
Suggestions
Add a 'Use when...' clause with trigger terms like 'ADR', 'architecture decision', 'document why we chose', 'technical decision record', 'decision log'
Replace vague 'comprehensive patterns' with specific actions like 'generate ADR templates', 'update decision status', 'link superseded decisions'
Include natural phrases users might say such as 'record this decision', 'why did we choose X', or 'document the tradeoffs'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and mentions actions like 'creating, maintaining, and managing', but lacks specific concrete actions like 'generate templates', 'link related decisions', or 'track decision status'. | 2 / 3 |
Completeness | Describes what the skill does but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | Includes 'Architecture Decision Records' and 'ADRs' which are relevant, but misses common variations users might say like 'technical decisions', 'design decisions', 'decision log', or 'why did we choose'. | 2 / 3 |
Distinctiveness Conflict Risk | ADRs are a specific domain which helps distinctiveness, but 'technical decisions' and 'documentation' aspects could overlap with general documentation or architecture skills without clearer triggers. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive and highly actionable skill for ADR management with excellent workflow clarity and concrete templates. The main weakness is verbosity - the skill could be more concise by assuming Claude's familiarity with ADR concepts and by splitting the extensive templates into separate referenced files rather than including them all inline.
Suggestions
Remove or significantly condense the 'What is an ADR?' section - Claude already understands this concept
Move the 5 full templates to separate files (e.g., templates/standard-adr.md, templates/lightweight-adr.md) and reference them from the main skill
Condense the 'When to Write an ADR' table - the distinction is straightforward and doesn't need extensive examples
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but verbose. It includes multiple full templates with extensive examples that could be condensed. The core concepts section explains what an ADR is, which Claude likely already knows. However, the templates themselves provide value as concrete references. | 2 / 3 |
Actionability | Provides fully executable guidance with complete markdown templates, concrete directory structures, actual CLI commands for adr-tools, and detailed checklists. The templates are copy-paste ready and the examples are specific and realistic. | 3 / 3 |
Workflow Clarity | Clear lifecycle diagram (Proposed → Accepted → Deprecated → Superseded), explicit review checklist with before/during/after phases, numbered migration plan in Template 4, and step-by-step process for creating new ADRs. Validation checkpoints are embedded in the review process. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but everything is inline in a single large file. The templates section alone is very long and could be split into separate files. References to external resources are provided but internal content organization could benefit from splitting templates into separate files. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
9c177eb
Table of Contents
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.