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.
61
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 that clearly communicates both purpose and trigger conditions. It excels at completeness and distinctiveness with explicit 'Use when' guidance and domain-specific terminology. The main weakness is moderate specificity - it could benefit from listing more concrete actions like creating, updating, or superseding ADRs.
Suggestions
Add more specific concrete actions such as 'create new ADRs, update existing records, mark decisions as superseded or deprecated, generate ADR indexes'
| 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 operations (create, update, supersede, deprecate) or what content elements are handled. | 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') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes'. Good coverage of how users naturally refer to this domain. | 3 / 3 |
Distinctiveness Conflict Risk | ADRs are a specific documentation format with distinct terminology. The triggers 'Architecture Decision Records', 'ADRs', 'architectural choices' are unlikely to conflict with general documentation or code skills. | 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') suggests poor organization rather than thoughtful progressive disclosure. A user cannot write an ADR from this main skill file alone.
Suggestions
Include at least one complete, copy-paste-ready ADR template directly in the main skill file so users can immediately start writing ADRs
Consolidate the 27 sub-skills into 3-5 coherent modules (e.g., 'Templates', 'Lifecycle Management', 'Best Practices') rather than fragmenting into individual sections
Add a concrete workflow with specific steps: 'Create file docs/adr/NNNN-title.md → Fill template sections → Submit for review → Update status after decision'
Remove or consolidate the duplicate and fragment sub-skills ('Positive' appears twice, 'Risks' and 'Negative' should be part of a larger consequences module)
| 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 the ADR creation process, and no guidance on what constitutes a complete ADR. 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 appear to be content 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
332e58b
- 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.