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.
77
65%
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
75%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 that clearly identifies its niche (ADRs) and includes an explicit 'Use when' clause with relevant trigger scenarios. Its main weaknesses are moderate specificity in the actions it describes and incomplete coverage of natural trigger terms users might use when they need this skill.
Suggestions
Add more specific concrete actions such as 'create ADR templates, update decision statuses (proposed/accepted/deprecated/superseded), link related decisions'
Expand trigger terms to include common variations like 'decision log', 'design decision', 'ADR template', 'why did we choose', or 'document architecture'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and some actions ('write and maintain', 'documenting', 'reviewing', 'establishing decision processes'), but doesn't list specific concrete actions like creating templates, updating statuses, linking related decisions, or specifying ADR format details. | 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 relevant terms like 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', but misses common variations users might say such as 'ADR template', 'decision log', 'tech decision doc', 'why did we choose', or 'design decision'. | 2 / 3 |
Distinctiveness Conflict Risk | ADRs are a very specific niche within technical documentation. The description clearly targets Architecture Decision Records specifically, making it unlikely to conflict with general documentation, code review, or other writing skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
55%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides highly actionable, well-structured ADR guidance with excellent templates and concrete examples, but suffers severely from verbosity and lack of progressive disclosure. Five complete templates with full example content are inlined, creating a massive document that wastes context window. The content would be far more effective as a concise overview linking to separate template files.
Suggestions
Move the five ADR templates into separate referenced files (e.g., templates/standard-adr.md, templates/lightweight-adr.md) and keep only a brief description and link for each in the main skill.
Remove the 'Core Concepts' section explaining what an ADR is and when to write one - Claude already knows this. Start directly with the templates and workflow.
Consolidate the review checklist and best practices into a single concise section, removing obvious advice like 'don't be vague' and 'don't skip context'.
Trim example template content significantly - one detailed template and one lightweight template would suffice, with the others available as referenced files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~300+ lines, explaining concepts Claude already knows well (what an ADR is, when to write one, basic lifecycle). Five full templates with extensive example content massively inflate token usage. The 'Core Concepts' section explaining what an ADR captures is unnecessary for Claude. | 1 / 3 |
Actionability | The skill provides fully concrete, copy-paste ready templates with realistic examples, executable bash commands for adr-tools, specific directory structures, and detailed checklists. Every template is complete and immediately usable. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced: creation process (copy template → fill in → submit PR → update index), review process with explicit before/during/after checklists, and the deprecation template includes a phased migration plan with validation steps. | 3 / 3 |
Progressive Disclosure | This is a monolithic wall of text with five full templates inlined, all example content expanded, and no references to external files. The templates should be in separate files with the SKILL.md providing an overview and links. The ADR index example, automation commands, and review checklist could all be separate referenced documents. | 1 / 3 |
Total | 8 / 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
91fe43e
- 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.