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.
55
Quality
52%
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 ./.agent/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
14%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a table of contents with no substantive content in the main file. The 4-step instructions are too vague to be actionable, and the excessive fragmentation into 27 sub-skills (including apparent duplicates and fragments like 'Positive', 'Negative', 'Risks') makes navigation confusing rather than helpful. A user cannot write an ADR from this skill without clicking through multiple sub-files.
Suggestions
Include at least one complete, copy-paste-ready ADR template directly in the main skill file so users can immediately start writing
Consolidate the fragmented sub-skills - 'Positive', 'Negative', 'Risks' should be sections within a template, not separate files
Add a concrete workflow with specific steps: 'Create file docs/adr/NNNN-title.md, copy template, fill sections in order X, Y, Z, submit for review'
Reduce sub-skills to logical groupings (e.g., 'Templates', 'Lifecycle', 'Best Practices') rather than 27 granular fragments
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably efficient but includes some unnecessary sections like 'Use this skill when' and 'Do not use this skill when' that explain obvious contexts. The main issue is the excessive fragmentation into 27 sub-skills, many of which appear to be fragments (e.g., 'Positive', 'Negative', 'Risks' as separate files). | 2 / 3 |
Actionability | The skill provides only vague 4-step instructions with no concrete examples, templates, or executable guidance in the main file. Everything is deferred to sub-skills, leaving the main skill body essentially useless for actually writing an ADR. | 1 / 3 |
Workflow Clarity | The 4-step instructions are extremely high-level with no validation checkpoints, no concrete sequence for creating an ADR, and no feedback loops. The workflow is essentially 'capture context, document options, record decision, link ADRs' without any actionable detail. | 1 / 3 |
Progressive Disclosure | While the skill attempts progressive disclosure, it fails badly - 27 sub-skills is excessive fragmentation, many links appear to be document fragments rather than coherent modules (e.g., 'Positive', 'Negative' as separate files), and the naming suggests poor organization (duplicate 'Positive' entries at #8 and #14). | 1 / 3 |
Total | 5 / 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
- Dokhacgiakhoa/antigravity-ide
- Commit
3395991
- 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.