architecture-decision-records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

Quality

58%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/antigravity-architecture-decision-records/SKILL.md

Quality

Content

56%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill delivers genuinely actionable material — five concrete ADR formats, executable adr-tools commands, and a solid review checklist — but buries it in a ~450-line monolith. Cutting the worked examples down to skeletons and moving templates into a references/ directory would substantially improve token efficiency and navigability.

Suggestions

Move the five full templates into separate files (e.g. references/templates/madr.md, y-statement.md) and keep only one condensed example inline, linking the rest — this addresses both conciseness and progressive disclosure.

Trim each template to a structural skeleton (headings plus one-line placeholders) instead of fully worked examples with dated, version-specific content (PostgreSQL 15, 2024 dates, MongoDB transactions) that will age and must be edited out by users.

Remove the duplication: the opening paragraph repeats the frontmatter description verbatim, and the 'Use/Do not use' bullet lists restate what the 'Limitations' section says — consolidate into one scope section.

Dimension	Reasoning	Score
Conciseness	The body is noticeably verbose: five fully worked ADR examples (~250 lines of filled-in sample content such as the complete PostgreSQL decision with pros/cons and implementation notes), plus the description repeated verbatim as the opening paragraph and redundant scope framing across 'Use this skill when', 'Do not use this skill when', and 'Limitations'. It is not level 1 because the content is organized and not explaining basic concepts Claude doesn't know, and not level 3 because the volume of illustrative filler across five templates goes beyond 'some unnecessary explanation'.	2 / 5
Actionability	The templates are copy-paste-ready markdown formats (MADR, lightweight, Y-statement, deprecation, RFC) and the adr-tools section gives executable bash commands ('adr new -s 3', 'adr generate toc'). It is not level 5 because the core 'Instructions' section is abstract ('Capture the decision context...') without concrete steps, and the worked examples contain time-sensitive details (PostgreSQL 15, 2024 dates) that a user must edit out.	4 / 5
Workflow Clarity	The lifecycle diagram, the sequenced 'Creating a New ADR' flow (copy template, fill, submit PR, update index), and the review checklist with explicit before-submission/during-review/after-acceptance checkpoints give a clear sequence with most checkpoints present. It is not level 5 because the top-level Instructions lack explicit validation or error-recovery feedback loops, and not level 3 because the review checklist supplies genuine validation checkpoints for the process.	4 / 5
Progressive Disclosure	Section headers provide reasonable structure, but there are no bundle files at all and roughly 250 lines of templates and example ADRs that clearly belong in separate reference files are fully inlined in SKILL.md. It is not level 4 because substantial content is mis-placed inline rather than split out, and not level 2 because navigation via headings is decent and the structure is not minimal.	3 / 5
	Total	13 / 20 Passed

Description

61%Weight 40%Scale 1-5

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 names a distinct, well-recognized domain and includes good natural trigger vocabulary, but it omits any explicit 'when to use this skill' guidance and relies on generic verbs ('creating, maintaining, and managing') instead of concrete capabilities. Adding a 'Use when...' clause and sharpening the actions would move it into the top tier.

Suggestions

Append an explicit trigger clause, e.g. 'Use when making or documenting significant architectural decisions, choosing technologies, or recording design trade-offs and their rationale.'

Replace the generic verbs with concrete capabilities such as 'Draft ADRs from decision context, structure considered options with trade-offs, track status through the proposed/accepted/superseded lifecycle, and index ADRs in a repo.'

Drop the filler phrase 'Comprehensive patterns for' — it adds tokens without adding information.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Architecture Decision Records (ADRs)') and lists actions ('creating, maintaining, and managing'), but these are generic verbs rather than concrete capabilities, and 'Comprehensive patterns' is padding. It is not level 4 because the actions lack the specificity of examples like 'extracts text, fills forms, merges documents', and not level 2 because the domain is clearly named with more than minimal action framing.	3 / 5
Completeness	It clearly answers 'what' (create, maintain, and manage ADRs capturing context and rationale) but contains no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It is not level 2 because the 'what' is concrete and well-stated, and not level 4 because the 'when' is entirely absent rather than merely implicit.	3 / 5
Trigger Term Quality	It includes strong natural terms users would say — 'Architecture Decision Records', 'ADRs', 'technical decisions', 'context and rationale'. It is not level 5 because common variations such as 'design decisions', 'decision log', 'MADR', or 'technology choices' are missing, and not level 3 because the core ADR vocabulary is well covered.	4 / 5
Distinctiveness Conflict Risk	'Architecture Decision Records (ADRs)' carves out a clear niche with minimal conflict risk against unrelated skills. It is not level 5 because without any 'when to use' framing it could overlap with general documentation or decision-making skills, and not level 3 because the ADR domain itself is quite specific rather than 'somewhat specific'.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: boisenoise/skills-collections
Path: skills/antigravity-architecture-decision-records/SKILL.md
Commit: 690de8f

Reviewed: 12 minutes ago

Table of Contents

Discovery Implementation Validation

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.