architecture-decision-records
Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
34
30%
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 ./plugins/antigravity-awesome-skills-claude/skills/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 say when they need this skill. The absence of a 'when to use' clause is the most significant weakness.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create an ADR, document an architecture decision, update decision records, or mentions ADR templates.'
List more specific concrete actions, e.g., 'Generate ADR markdown files from templates, update ADR statuses (proposed/accepted/deprecated/superseded), link related decisions, and maintain an ADR index.'
Include additional natural trigger terms users might say, such as 'decision log', 'ADR template', 'document why we chose', 'architecture decision', or 'adr-tools'.
| 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' 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 'adr-tools'. | 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. The lack of explicit triggers increases conflict risk. | 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 on ADRs but fails as a SKILL.md for Claude. It is excessively verbose, explaining concepts Claude already understands, and embeds five full-length template examples inline rather than splitting them into referenced files. The core instructions are paradoxically thin (4 bullets) while the surrounding content is bloated, making it unclear what Claude should actually do when asked to create an ADR.
Suggestions
Extract the 5 templates into separate bundle files (e.g., templates/standard-adr.md, templates/lightweight-adr.md) and reference them from SKILL.md with one-line descriptions of when to use each.
Remove the 'Core Concepts' section entirely—Claude knows what ADRs are, when to write them, and their lifecycle states.
Expand the 4-bullet 'Instructions' section into a clear sequenced workflow with validation steps, e.g.: 1) Ask user for context/constraints, 2) Select appropriate template, 3) Draft ADR, 4) Validate against review checklist, 5) Present for feedback.
Cut the 'Best Practices', 'Resources', and 'Review Process' sections down to essential items or move them to a separate reference file, keeping SKILL.md under 80 lines.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ 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 entirely unnecessary for Claude, and the templates are padded with lengthy fictional examples rather than lean, reusable skeletons. | 1 / 3 |
Actionability | The templates are concrete and copy-paste ready, and the adr-tools commands are executable. However, the skill reads more like a reference document than actionable instructions—it doesn't clearly tell Claude what to do when asked to create an ADR (e.g., which template to default to, how to gather context from the user, what questions to ask). The instructions section is only 4 vague bullet points. | 2 / 3 |
Workflow Clarity | The review checklist provides a reasonable workflow with before/during/after phases, and the deprecation template includes a migration plan. However, the core instructions (4 bullet points) lack a clear sequenced workflow with validation checkpoints. There's no explicit feedback loop for validating ADR quality before finalizing, and the relationship between the multiple templates and when to use each is not clearly sequenced. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with five full template examples, management guidelines, review checklists, best practices, and resources all inline. No bundle files are provided, yet the content desperately needs splitting—templates should be in separate files, with the SKILL.md providing a concise overview and navigation. The directory structure example suggests external files but none exist. | 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
- sickn33/antigravity-awesome-skills
- Commit
4cc48db
- 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.