CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architecture-decision-records

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

52

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/antigravity-bundle-architecture-design/skills/architecture-decision-records/SKILL.md
SKILL.md
Quality
Evals
Security

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 body is well-organized and genuinely actionable — templates, tooling commands, and review checklists give Claude concrete material to work from. Its main weaknesses are token bloat from fully worked example ADRs and the absence of any progressive disclosure: everything, including five complete templates, lives inline in one long file.

Suggestions

Strip the five templates to their skeleton structures and move the full worked examples into references/ files (e.g., references/templates.md, references/examples.md), linked one level deep from SKILL.md.

Replace the four abstract 'Instructions' steps with the concrete end-to-end workflow already embedded in the README example (copy template → fill → PR review against the checklist → update index), stated as the skill's own process.

Cut scenario-specific filler inside templates (e.g., the detailed PostgreSQL/MySQL/MongoDB pros-cons in Template 1) down to placeholder guidance, since Claude can generate domain content itself.

DimensionReasoningScore

Conciseness

Roughly 250 of the ~436 lines are five fully worked example ADRs stuffed with scenario-specific filler (a ~95-line e-commerce PostgreSQL ADR with pros/cons for MySQL and MongoDB, a six-week migration plan, RFC event schemas) that a competent model can generate itself — only the template skeletons add value. This matches anchor 2 ('noticeably verbose; several unnecessary explanations or padded sections'); it is not a 3 because the padding is extensive rather than occasional.

2 / 5

Actionability

The skill provides copy-paste-ready templates in five formats, executable adr-tools commands ('adr new -s 3 ...'), a concrete directory structure, and a review checklist. It stops short of anchor 5 because the top-level 'Instructions' are four abstract steps ('Capture the decision context...') whose specifics depend entirely on the templates, and there are no commands for the non-adr-tools path.

4 / 5

Workflow Clarity

There is a clear sequence — when-to-write table, lifecycle diagram (Proposed → Accepted → Deprecated → Superseded), creation steps (copy template → fill → PR → update index), and a before/during/after review checklist acting as checkpoints. Not anchor 5 because the primary workflow is embedded inside the README example rather than stated as the skill's own validated process with explicit feedback loops.

4 / 5

Progressive Disclosure

Section organization is good (Use/Do not use, Core Concepts, Templates, Management, Review, Best Practices), but the skill has no bundle files and inlines ~250 lines of full templates that clearly belong in references/ (e.g., templates/madr.md). This matches anchor 3 ('some structure; content that should be separate is inline') rather than 2, since headers and navigation within the single file are reasonable.

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 clearly identifies its domain and purpose but reads as a summary rather than a trigger: it lacks any 'Use when...' guidance and its action verbs are generic. Adding explicit trigger phrases and more concrete capability actions would raise both completeness and specificity.

Suggestions

Append an explicit trigger clause, e.g. 'Use when making or documenting significant architectural decisions, adopting new frameworks or databases, or when the user mentions ADRs, design decisions, or decision records.'

Replace generic verbs ('creating, maintaining, and managing') with concrete capabilities such as 'draft ADRs from MADR/Y-statement templates, manage ADR status lifecycles, and maintain a supersede chain with adr-tools'.

Add natural synonyms users would say ('design decisions', 'decision log', 'architecture choices') to broaden trigger coverage.

DimensionReasoningScore

Specificity

The description names the domain ("Architecture Decision Records (ADRs)") with a purpose clause ("capture the context and rationale behind significant technical decisions"), but the actions "creating, maintaining, and managing" are generic verbs rather than concrete operations. This matches anchor 3 (domain plus a couple of actions, not comprehensive) — anchor 4 requires several genuinely specific actions like 'extracts text, fills forms, converts pages'.

3 / 5

Completeness

The 'what' is clear (patterns for creating, maintaining, and managing ADRs), but there is no 'Use when...' clause or any equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 3. It is not a 4 because 'when' is entirely absent rather than just imprecise.

3 / 5

Trigger Term Quality

It includes both the full term and the acronym ("Architecture Decision Records (ADRs)") plus natural phrases like "technical decisions" and "context and rationale", giving good keyword coverage. It falls short of anchor 5 because common synonyms a user might say — 'design decisions', 'decision log', 'documenting decisions' — are missing.

4 / 5

Distinctiveness Conflict Risk

ADRs are a well-defined niche with distinct terminology, so the skill is mostly distinguishable from others. Minor overlap risk remains with general documentation and technical-writing skills, which matches anchor 4 ('mostly distinct; minor overlap risk') rather than anchor 5's minimal-conflict profile.

4 / 5

Total

14

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

administrakt0r/AI-Agents-Safe-Coding-Skills

Path

plugins/antigravity-bundle-architecture-design/skills/architecture-decision-records/SKILL.md

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.