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, or maintain a decision log.'
List more specific concrete actions, e.g., 'Generate ADR templates, update decision statuses (proposed/accepted/deprecated/superseded), link related decisions, and format ADR markdown files.'
Include additional natural trigger terms users might say, such as 'decision log', 'ADR template', 'document why we chose', 'architecture decision', or 'decision record'.
| 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 | Describes what it 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 rubric guidelines, 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 'why did we choose'. | 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 is a comprehensive reference document about ADRs but fails as a SKILL.md for Claude. It over-explains concepts Claude already understands, includes five full template examples inline creating massive bloat, and lacks clear progressive disclosure. The actionable content (templates, adr-tools commands, review checklist) is valuable but buried in excessive context.
Suggestions
Reduce to one primary template inline with brief notes on variations, moving additional templates to separate referenced files (e.g., templates/standard-adr.md, templates/lightweight-adr.md).
Remove the 'Core Concepts' section entirely — Claude knows what ADRs are, when to write them, and their lifecycle states.
Restructure the top-level instructions into a clear numbered workflow with validation checkpoints (e.g., 'Verify context section answers WHY before proceeding to options').
Move the review checklist, best practices, and management sections to separate referenced files to improve progressive disclosure.
| 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 fictional content is excessive — one template with brief variations would suffice. The 'Core Concepts' section is entirely unnecessary for Claude. | 1 / 3 |
Actionability | Provides concrete templates and bash commands for adr-tools, which is useful. However, much of the content is descriptive rather than instructive — it shows example ADR content rather than giving Claude executable steps for creating ADRs in a specific project context. The templates are copy-paste ready but the skill reads more like a reference document than actionable instructions. | 2 / 3 |
Workflow Clarity | The four-step instruction sequence is present but minimal. The review checklist provides good checkpoints, but there's no clear feedback loop for validation — e.g., no step saying 'verify the ADR addresses all checklist items before submitting.' The creation workflow (copy template, fill in, submit PR, update index) is listed but buried in the ADR Index section rather than being the primary workflow. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with everything inline. Five complete template examples, management details, automation commands, review checklists, and best practices are all in one file. Templates should be in separate files with references from the main skill. No external file references or layered structure. | 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
f1697b6
- 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.