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.
73
58%
Does it follow best practices?
Impact
99%
1.45xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/documentation-generation/skills/architecture-decision-records/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description with a clear 'Use when' clause and good trigger term coverage for the ADR domain. Its main weakness is that the 'what' portion could be more specific about the concrete actions it performs beyond 'write and maintain.' Overall it performs well for skill selection purposes.
Suggestions
Expand the capability list with more specific actions, e.g., 'Write and maintain Architecture Decision Records (ADRs): create new ADR files from templates, update decision statuses, link related decisions, and generate ADR indexes.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and some actions ('write and maintain'), but doesn't list multiple specific concrete actions like creating templates, linking related decisions, tracking status changes, or generating indexes. | 2 / 3 |
Completeness | Clearly answers both 'what' (write and maintain ADRs following best practices) and 'when' (explicit 'Use when' clause covering documenting decisions, reviewing past choices, or establishing decision processes). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes' — these cover the terms users would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | ADRs are a very specific niche within technical documentation. The triggers are distinct enough ('Architecture Decision Records', 'ADRs', 'architectural choices') that this is unlikely to conflict with general documentation or coding skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a comprehensive ADR tutorial or wiki page than a focused skill for Claude. It is heavily padded with explanatory content Claude doesn't need (what an ADR is, when to use one, lifecycle diagrams) and includes five full-length templates inline that massively inflate token usage. The content would benefit greatly from being restructured into a concise overview with templates split into separate referenced files.
Suggestions
Move the 5 templates into separate files (e.g., templates/standard-adr.md, templates/lightweight-adr.md) and reference them from the main skill with one-line descriptions of when to use each.
Remove the 'Core Concepts' section entirely—Claude knows what ADRs are. Replace with a brief 2-3 line instruction on the preferred approach.
Add a clear sequential workflow at the top: 'When asked to write an ADR: 1. Identify which template fits, 2. Gather context by asking X questions, 3. Draft using template, 4. Verify against checklist.'
Cut the 'When to Use This Skill' and 'When to Write an ADR' sections—these are meta-descriptions that don't help Claude execute the task.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~300+ lines, explaining concepts Claude already knows (what an ADR is, when to write one, basic lifecycle). Five full templates with extensive example content massively bloat the token budget. The 'Core Concepts' section is entirely unnecessary for Claude. | 1 / 3 |
Actionability | The templates are concrete and copy-paste ready, and the adr-tools commands are executable. However, much of the content describes rather than instructs—it's more of a reference document than actionable guidance for Claude on how to create ADRs in practice. There's no clear 'when given X, do Y' instruction pattern. | 2 / 3 |
Workflow Clarity | The review checklist provides a reasonable workflow, and the deprecation template includes a migration plan with phases. However, the core workflow for creating an ADR is scattered across sections rather than presented as a clear sequential process. There are no validation checkpoints for the actual writing process (e.g., verify context is sufficient before proceeding). | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text with five full templates inlined, a complete ADR index example, directory structure, automation commands, review checklist, and best practices all in one file. The templates alone should be in separate referenced files. No external references are used to manage the content volume. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- wshobson/agents
- Commit
27a7ed9
- Reviewed
Table of Contents
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.