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, and uses natural trigger terms that users would actually say. Its main weakness is that the capability listing could be more specific about concrete actions beyond 'write and maintain', such as creating templates, updating decision statuses, or generating specific ADR sections.
Suggestions
Add more specific concrete actions like 'create ADR templates, update decision statuses (proposed/accepted/deprecated/superseded), generate ADR indexes' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs/technical decision documentation) 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 specific ADR format elements. | 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 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 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 is essentially a comprehensive ADR reference guide rather than an efficient, actionable skill for Claude. It over-explains concepts Claude already understands, inlines five full template examples that bloat the document enormously, and lacks a clear Claude-facing workflow for actually producing ADRs. The content quality is decent as documentation but poor as a skill optimized for Claude's context window.
Suggestions
Reduce to one primary template (e.g., Standard MADR) inline, and move the other 4 templates to separate bundle files referenced with clear links.
Remove the 'Core Concepts' section entirely—Claude knows what ADRs are, when to write them, and their lifecycle states.
Add an explicit Claude-facing workflow at the top: e.g., '1. Determine decision scope → 2. Gather context from user → 3. Select template (default: Standard) → 4. Draft ADR → 5. Validate against checklist.'
Cut the 'Best Practices' Do's/Don'ts and 'Resources' sections, which are general advice Claude already knows and external links it cannot access.
| 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 prose content that could be drastically condensed. The 'Core Concepts' section is entirely unnecessary for Claude. | 1 / 3 |
Actionability | Provides concrete templates and examples that are copy-paste ready, plus adr-tools commands. However, the skill reads more like a reference document than actionable instructions for Claude—it doesn't clearly tell Claude what to do when asked to write an ADR (e.g., which template to default to, how to gather context from the user). | 2 / 3 |
Workflow Clarity | The review checklist provides a reasonable workflow, and the deprecation template includes a migration plan. However, there's no clear workflow for Claude itself—no sequenced steps like 'ask user for context → select template → draft ADR → validate sections.' The process for creating an ADR is buried in the index README rather than being a primary workflow. | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with no bundle files to offload detail into. Five full template examples are inlined when they could be separate files. The skill would benefit enormously from a concise overview pointing to separate template files, but instead everything is crammed into one document. | 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
99da384
- 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.