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.
82
Quality
80%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./docs/v19.7/configuration/agent/skills_external/antigravity-awesome-skills-main/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 well-structured description with explicit 'Use when' triggers and good keyword coverage for the ADR domain. The main weakness is that the capabilities could be more specific about concrete actions (e.g., 'create ADR templates', 'number and link decisions', 'track superseded records'). Overall, it effectively communicates when Claude should select this skill.
Suggestions
Add more specific concrete actions like 'create ADR templates, track decision status, link related decisions, manage superseded records' to improve specificity
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and some actions ('Write and maintain', 'documenting', 'reviewing', 'establishing'), but doesn't list comprehensive concrete actions like specific ADR components, templates, or operations. | 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 strong natural keywords users would say: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes'. | 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
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides excellent actionable content with complete, copy-paste ready templates and clear workflows. However, it suffers from poor progressive disclosure - all content is crammed into one large file rather than being appropriately split. The verbosity could be reduced by assuming Claude understands basic ADR concepts and moving detailed templates to referenced files.
Suggestions
Move the 5 detailed templates to a separate TEMPLATES.md file and reference it from the main skill
Remove the 'What is an ADR?' section - Claude already knows this concept
Condense the 'Use this skill when' and 'Do not use this skill when' sections into a brief table
Add a quick-start section at the top with just one minimal template, then reference the full templates file for comprehensive options
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but verbose. It includes 5 full templates with extensive examples that could be condensed or moved to separate files. The core concepts section explains what an ADR is, which Claude likely already knows. | 2 / 3 |
Actionability | Provides fully executable templates with complete markdown examples, concrete directory structures, actual CLI commands for adr-tools, and copy-paste ready content. The templates are immediately usable. | 3 / 3 |
Workflow Clarity | Clear lifecycle diagram (Proposed → Accepted → Deprecated → Superseded), explicit review checklist with before/during/after phases, and the deprecation template includes a phased migration plan with validation steps. | 3 / 3 |
Progressive Disclosure | This is a monolithic wall of text with all 5 templates inline. The content would benefit greatly from splitting templates into separate files (e.g., TEMPLATES.md) and keeping SKILL.md as a concise overview with references. | 1 / 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.
- Repository
- duclm1x1/Dive-Ai
- Commit
20ba150
- 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.