architecture-decision-records
Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
39
37%
Does it follow best practices?
Impact
—
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 adding natural trigger terms users would say when needing this skill.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, update, or review an ADR, document an architecture decision, or manage a decision log.'
List more specific concrete actions such as 'generate ADR templates from a standard format, update ADR statuses (proposed/accepted/deprecated), link related ADRs, and summarize decision history.'
Include additional natural trigger terms like 'decision log', 'ADR template', 'architecture documentation', 'record a technical decision', or 'doc/adr'.
| 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' is also somewhat vague, placing this at 1. | 1 / 3 |
Trigger Term Quality | Includes 'Architecture Decision Records' and 'ADRs' which are good trigger terms, plus 'technical decisions' and 'rationale.' However, it misses common variations users might say like 'ADR template', 'decision log', 'architecture docs', 'doc/adr', or 'record a decision.' | 2 / 3 |
Distinctiveness Conflict Risk | ADRs are a fairly specific niche, which helps distinctiveness. However, the mention of 'technical decisions' and 'context and rationale' could overlap with general documentation or technical writing skills. More explicit scoping would reduce conflict risk. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with excellent, realistic templates and concrete tooling commands, but it is severely bloated. It explains concepts Claude already understands, inlines massive template examples that should be in separate referenced files, and reads more like a comprehensive guide for human developers than a concise skill for Claude. The content would benefit enormously from splitting templates into separate files and trimming explanatory sections.
Suggestions
Move the five full ADR templates into separate referenced files (e.g., templates/standard-adr.md, templates/lightweight-adr.md) and keep only a brief summary with links in SKILL.md.
Remove the 'Core Concepts' section entirely—Claude already knows what ADRs are, their lifecycle, and when to write them.
Cut the 'Best Practices' do's/don'ts section or reduce it to 2-3 non-obvious points; most items are common sense for Claude.
Add an explicit validation step in the workflow, e.g., 'After drafting, verify all checklist items are addressed before submitting for review.'
| 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. | 1 / 3 |
Actionability | Provides multiple complete, copy-paste-ready templates with realistic examples. Includes concrete CLI commands for adr-tools, specific directory structures, and a detailed review checklist. The templates are fully fleshed out with real-world scenarios rather than abstract placeholders. | 3 / 3 |
Workflow Clarity | The four-step instructions are clear but very high-level. The review checklist provides good sequencing (before/during/after submission), and the deprecation template includes a phased migration plan. However, there are no explicit validation checkpoints or feedback loops for the ADR creation process itself—no step says 'verify X before proceeding.' | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with five full templates inlined, plus management guidance, automation commands, review checklists, and best practices all in one file. No bundle files are provided, but the content desperately needs splitting—templates should be in separate files with the SKILL.md providing an overview and links. | 1 / 3 |
Total | 7 / 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
8ac11ab
- 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.