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
100%
1.61xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/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 skill description that clearly identifies its niche (ADRs), includes an explicit 'Use when' clause with relevant triggers, and is distinctive enough to avoid conflicts with other skills. The main weakness is that the capability listing could be more specific about concrete actions beyond 'write and maintain' — for example, mentioning template creation, status tracking, or specific ADR formats.
Suggestions
Add more specific concrete actions such as 'create ADR templates, track decision status (proposed/accepted/deprecated), link related decisions' to improve specificity.
| 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, linking decisions, tracking status changes, 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 strong natural keywords users would say: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes'. These cover the main ways users would refer to this topic. | 3 / 3 |
Distinctiveness Conflict Risk | ADRs are a very specific niche within technical documentation. The triggers are distinct ('Architecture Decision Records', 'ADRs', 'architectural choices') and 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 article than a focused skill for Claude. It is extremely verbose, inlining five full template examples with fictional content, extensive best practices, and review checklists — most of which Claude already understands conceptually. The skill lacks a clear directive workflow telling Claude what to do when asked to create an ADR, and all content is crammed into a single file with no progressive disclosure.
Suggestions
Reduce to one primary template (MADR) with brief notes on when to use lightweight or Y-statement variants, moving full alternative templates to separate bundle files.
Add a clear 'How to Use This Skill' workflow section at the top: e.g., 1) Ask user for context/constraints, 2) Select appropriate template, 3) Draft ADR, 4) Validate against checklist.
Remove explanatory content Claude already knows (what an ADR is, basic do's/don'ts of documentation) and focus on project-specific conventions or non-obvious patterns.
Split the review checklist, management/directory structure, and adr-tools commands into separate bundle files referenced from the main SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Explains basic concepts Claude already knows (what an ADR is, when to write one, lifecycle states). Five full template examples with extensive fictional content is excessive — one template with brief variations would suffice. The 'Core Concepts' section, 'Best Practices' do's/don'ts, and 'Review Process' checklist all explain things Claude inherently understands about documentation practices. | 1 / 3 |
Actionability | Provides concrete templates that are copy-paste ready, and the adr-tools commands are executable. However, the skill is more of a reference document than actionable guidance — it doesn't clearly instruct Claude on what to do when asked to write an ADR (e.g., which template to default to, how to gather context from the user). The templates are examples rather than executable instructions. | 2 / 3 |
Workflow Clarity | The review checklist provides a sequence (before/during/after), and the 'Creating a New ADR' section has numbered steps. However, there's no clear workflow for Claude itself — when a user asks for an ADR, what steps should Claude follow? Which template should it pick? How should it gather missing context? The migration plan in Template 4 shows good sequencing but that's example content, not skill workflow. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no bundle files or external references for the detailed templates. All five templates are inlined in full, making the skill extremely long. The templates, review checklist, and management sections should be split into separate referenced files. No bundle structure exists to support this. | 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
- Dicklesworthstone/pi_agent_rust
- Commit
c21e340
- 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.