CtrlK
BlogDocsLog inGet started
Tessl Logo

architecture-decision-records

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

63

Quality

55%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/architecture-decision-records/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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) and mentions general actions, but lacks the explicit trigger guidance needed for Claude to know when to select this skill. It would benefit from concrete action examples and a 'Use when...' clause with natural user phrases.

Suggestions

Add a 'Use when...' clause with trigger terms like 'ADR', 'architecture decision', 'document why we chose', 'technical decision record', 'decision log'

Replace vague 'comprehensive patterns' with specific actions like 'generate ADR templates', 'update decision status', 'link superseded decisions'

Include natural phrases users might say such as 'record this decision', 'why did we choose X', or 'document the tradeoffs'

DimensionReasoningScore

Specificity

Names the domain (ADRs) and mentions actions like 'creating, maintaining, and managing', but lacks specific concrete actions like 'generate templates', 'link related decisions', or 'track decision status'.

2 / 3

Completeness

Describes what the skill does but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill.

1 / 3

Trigger Term Quality

Includes 'Architecture Decision Records' and 'ADRs' which are relevant, but misses common variations users might say like 'technical decisions', 'design decisions', 'decision log', or 'why did we choose'.

2 / 3

Distinctiveness Conflict Risk

ADRs are a specific domain which helps distinctiveness, but 'technical decisions' and 'documentation' aspects could overlap with general documentation or architecture skills without clearer triggers.

2 / 3

Total

7

/

12

Passed

Implementation

77%

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

This is a comprehensive and highly actionable skill for ADR management with excellent workflow clarity and concrete templates. The main weakness is verbosity - the skill could be more concise by assuming Claude's familiarity with ADR concepts and by splitting the extensive templates into separate referenced files rather than including them all inline.

Suggestions

Remove or significantly condense the 'What is an ADR?' section - Claude already understands this concept

Move the 5 full templates to separate files (e.g., templates/standard-adr.md, templates/lightweight-adr.md) and reference them from the main skill

Condense the 'When to Write an ADR' table - the distinction is straightforward and doesn't need extensive examples

DimensionReasoningScore

Conciseness

The skill is comprehensive but verbose. It includes multiple full templates with extensive examples that could be condensed. The core concepts section explains what an ADR is, which Claude likely already knows. However, the templates themselves provide value as concrete references.

2 / 3

Actionability

Provides fully executable guidance with complete markdown templates, concrete directory structures, actual CLI commands for adr-tools, and detailed checklists. The templates are copy-paste ready and the examples are specific and realistic.

3 / 3

Workflow Clarity

Clear lifecycle diagram (Proposed → Accepted → Deprecated → Superseded), explicit review checklist with before/during/after phases, numbered migration plan in Template 4, and step-by-step process for creating new ADRs. Validation checkpoints are embedded in the review process.

3 / 3

Progressive Disclosure

Content is well-organized with clear sections, but everything is inline in a single large file. The templates section alone is very long and could be split into separate files. References to external resources are provided but internal content organization could benefit from splitting templates into separate files.

2 / 3

Total

10

/

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

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

Warning

Total

10

/

11

Passed

Repository
sickn33/antigravity-awesome-skills
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.