architecture-decision-records
Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
43
30%
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 ./skills/antigravity-architecture-decision-records/SKILL.mdQuality
Discovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies a clear domain (ADRs) but relies on generic verbs and lacks explicit trigger guidance ('Use when...'). It would benefit from listing specific concrete actions and including natural trigger terms that users would actually say when needing this skill.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create an ADR, document an architecture decision, update a decision log, or work with ADR templates.'
List more specific concrete actions such as 'generate ADR markdown templates, update decision status (proposed/accepted/deprecated), link superseding decisions, and format ADR numbering.'
Include additional natural trigger terms users might say: 'decision log', 'ADR template', 'document architecture choice', 'adr-tools', 'record technical decision'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Architecture Decision Records/ADRs) and some actions ('creating, maintaining, and managing'), but these are fairly generic verbs. It doesn't list specific concrete actions like 'generate ADR templates, update status fields, link related decisions, format markdown files.' | 2 / 3 |
Completeness | It describes what the skill does (patterns for creating/maintaining ADRs) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' portion is also somewhat vague, placing this at 1. | 1 / 3 |
Trigger Term Quality | Includes 'Architecture Decision Records', 'ADRs', and 'technical decisions' which are relevant keywords. However, it misses common variations users might say like 'ADR template', 'document architecture decision', 'decision log', 'tech decision record', or 'adr-tools'. | 2 / 3 |
Distinctiveness Conflict Risk | ADRs are a fairly specific niche which helps distinctiveness, but the broad language around 'technical decisions' and 'maintaining' documentation could overlap with general documentation or technical writing skills. | 2 / 3 |
Total | 7 / 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 page than an efficient skill file for Claude. It is extremely verbose, explaining concepts Claude already understands and including five full template examples inline rather than referencing them externally. While the templates themselves are well-crafted and the content is accurate, the lack of concise actionable instructions and poor progressive disclosure significantly reduce its effectiveness as a skill.
Suggestions
Reduce the body to a concise overview with clear step-by-step instructions for Claude (e.g., 'When asked to create an ADR: 1. Determine scope, 2. Select template based on X criteria, 3. Fill in sections...') and move the five templates into separate bundle files referenced from SKILL.md.
Remove the 'Core Concepts' section entirely—Claude already knows what ADRs are, when to write them, and their lifecycle states.
Add a decision tree or clear criteria for which template to use (Standard vs Lightweight vs Y-Statement vs Deprecation vs RFC) so Claude can make an actionable choice rather than presenting all five templates inline.
Cut the 'Best Practices' do's/don'ts and 'Resources' sections, which are generic advice Claude already follows, and instead add a brief validation checklist Claude should run through after drafting an ADR.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. Explains basic concepts Claude already knows (what an ADR is, when to write one, lifecycle states). Five full template examples with extensive inline content that could be referenced externally. The 'Core Concepts' section is unnecessary for Claude, and the best practices/do's/don'ts are largely common sense that Claude would already follow. | 1 / 3 |
Actionability | Provides concrete templates and examples which are useful, and the adr-tools commands are executable. However, the skill is more of a reference document than actionable instructions—it doesn't clearly tell Claude what to do step-by-step when asked to create an ADR. The templates are copy-paste ready but the instructions section (4 bullet points) is vague. | 2 / 3 |
Workflow Clarity | The 4-step instructions are too high-level to guide a multi-step process. The review checklist provides good checkpoints, and the deprecation template includes a phased migration plan. However, there's no clear workflow for Claude to follow when creating an ADR—no validation steps, no decision points about which template to use, and no feedback loop for reviewing completeness. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with everything inline. Five complete template examples, a full directory structure, automation commands, review checklist, and best practices are all crammed into a single file. No bundle files are provided, and there are no references to external files that could hold the templates or detailed examples separately. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- boisenoise/skills-collections
- Commit
431bfad
- 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.