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.
Install with Tessl CLI
npx tessl i github:Dicklesworthstone/pi_agent_rust --skill architecture-decision-records81
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 with explicit 'Use when...' guidance and good trigger term coverage for the ADR domain. The main weakness is that the capabilities could be more specific about concrete actions beyond 'write and maintain'. Overall, it effectively distinguishes itself and provides clear selection criteria.
Suggestions
Add more specific concrete actions such as 'create ADR templates', 'update decision status', 'link related decisions', or 'generate ADR indexes' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and mentions actions like 'write', 'maintain', and 'documenting', but lacks specific concrete actions like 'create templates', 'link related decisions', or 'track decision status'. | 2 / 3 |
Completeness | Clearly answers both what ('Write and maintain Architecture Decision Records following best practices') and when ('Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes'). | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes' - good coverage of how users would phrase requests. | 3 / 3 |
Distinctiveness Conflict Risk | ADRs are a specific documentation format with clear niche; unlikely to conflict with general documentation or code skills due to explicit 'Architecture Decision Records' and 'ADRs' terminology. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides excellent actionable content with complete, executable templates and clear workflows, but suffers significantly from verbosity. It explains concepts Claude already knows (what an ADR is, when to write one) and includes 5 full template examples when 1-2 would suffice. The content would be more effective at 25% of its current length with detailed templates moved to separate reference files.
Suggestions
Remove explanatory sections like 'What is an ADR?' and 'When to Use This Skill' - Claude understands these concepts
Keep only 1-2 templates inline (Standard and Lightweight), move others to a separate TEMPLATES.md file
Condense the 'Best Practices' and 'Review Process' sections into a brief checklist
Move the 'ADR Management' directory structure and automation commands to a separate SETUP.md reference file
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 400+ lines with extensive explanations of what ADRs are, when to use them, and multiple full template examples. Claude already understands documentation concepts; this could be reduced to 1-2 templates with brief guidance. | 1 / 3 |
Actionability | Provides fully executable templates with complete examples, specific bash commands for adr-tools, concrete directory structures, and copy-paste ready markdown. The templates are immediately usable. | 3 / 3 |
Workflow Clarity | Clear lifecycle diagram (Proposed → Accepted → Deprecated → Superseded), explicit review checklist with checkboxes, numbered migration phases in deprecation template, and step-by-step process for creating new ADRs. | 3 / 3 |
Progressive Disclosure | Content is organized with clear sections and headers, but everything is inline in one massive file. The multiple full templates and extensive examples could be split into separate reference files with SKILL.md providing just the overview and one primary template. | 2 / 3 |
Total | 9 / 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.
- 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.