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 architect...
75
Quality
65%
Does it follow best practices?
Impact
91%
1.15xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/antigravity-architecture-decision-records/SKILL.mdQuality
Discovery
75%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 effectively identifies its niche (ADRs) and includes an explicit 'Use when' clause, making it complete and distinctive. However, it could benefit from more specific action verbs and additional natural trigger terms that users might say when needing this skill. The truncation also limits full evaluation of trigger coverage.
Suggestions
Add more specific actions like 'create ADR templates', 'update decision status', 'link superseded decisions', or 'generate ADR indexes'
Include additional natural trigger terms users might say: 'design decisions', 'why did we choose', 'decision log', 'technical rationale', 'document architecture choice'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and some actions ('Write and maintain', 'documenting', 'reviewing'), but lacks comprehensive specific actions like 'create templates', 'link related decisions', or 'track decision status'. | 2 / 3 |
Completeness | Clearly answers both what ('Write and maintain Architecture Decision Records') and when ('Use when documenting significant technical decisions, reviewing past architect...') with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes 'ADRs', 'Architecture Decision Records', 'technical decisions', and 'architect...' (truncated), but missing common variations like 'design decisions', 'tech choices', 'decision log', or 'why did we choose'. | 2 / 3 |
Distinctiveness Conflict Risk | ADRs are a specific documentation format with clear niche; unlikely to conflict with general documentation or code review skills due to explicit 'Architecture Decision Records' terminology. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
55%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 clear workflows and concrete templates, but severely violates token efficiency principles. The content is comprehensive to a fault - it includes extensive explanations of ADR concepts, five complete templates inline, and detailed management guidance that should be progressively disclosed through separate files rather than presented as a single massive document.
Suggestions
Move templates 2-5 to a separate TEMPLATES.md file, keeping only one representative template inline with links to others
Extract ADR Management, Review Process, and Best Practices sections into separate reference files (e.g., MANAGEMENT.md, REVIEW.md)
Remove explanatory content like 'What is an ADR?' and 'When to Write an ADR' - Claude knows these concepts
Condense the main SKILL.md to a quick-start overview (~50 lines) with clear links to detailed reference materials
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 400+ lines with extensive explanations of ADR concepts Claude already knows. Multiple full templates with lengthy examples could be condensed significantly or moved to separate reference files. | 1 / 3 |
Actionability | Provides fully executable templates, concrete bash commands for adr-tools, complete markdown examples that are copy-paste ready, and specific directory structures. The guidance is highly actionable. | 3 / 3 |
Workflow Clarity | Clear lifecycle diagram, explicit review checklist with validation steps, numbered migration phases with specific timelines, and a well-defined creation process with PR review workflow. | 3 / 3 |
Progressive Disclosure | Monolithic wall of content with everything inline. Five complete templates, management details, automation commands, and review processes should be split into separate reference files with the SKILL.md providing a concise overview. | 1 / 3 |
Total | 8 / 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
5c5ae21
- 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.