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

62%

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 ./plugins/AI-Agents-Safe-Coding-Skills/skills/architecture-decision-records/SKILL.md

Quality

Content

63%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 content is highly actionable with complete templates and commands, but it is over-long for a SKILL.md: it inlines multiple full ADR examples and restates basic concepts Claude already knows, and it does not split reference material into bundle files.

Suggestions

Move the five full ADR templates into separate reference files (e.g. references/templates/*.md) and link to them from a concise overview, reducing the inlined template bulk.

Trim the 'What is an ADR?' explanation and Do's/Don'ts that restate knowledge Claude already has, keeping only the workflow-specific guidance.

Add an explicit validation step in the main Instructions sequence (e.g. 'verify the ADR passes the review checklist before updating the index') to add a feedback loop for the batch/management operations.

Dimension	Reasoning	Score
Conciseness	At ~437 lines the body inlines five full multi-page ADR templates and re-explains basic ADR concepts ('Context', 'Decision', 'Consequences') Claude already knows, which is noticeably verbose with several padded sections.	2 / 5
Actionability	It provides five complete, copy-paste-ready ADR templates, executable adr-tools commands, and a concrete directory layout, covering the common cases fully.	5 / 5
Workflow Clarity	The lifecycle, review checklist, and 'Creating a New ADR' steps give a clear sequence with explicit review checkpoints, though the main Instructions list is a high-level four-step sequence without validation feedback loops.	4 / 5
Progressive Disclosure	Structure is sectioned but everything is inlined into a single monolithic SKILL.md with no bundle files; the five full templates and API/management material that belong in separate reference files are not split out or clearly signaled as one-level-deep references.	3 / 5
	Total	14 / 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 a specific, distinctive niche and uses strong domain keywords, but it omits an explicit 'Use when...' trigger clause and lists only high-level verbs rather than a comprehensive set of concrete actions.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when making or documenting significant architectural decisions, choosing technologies, or onboarding teams to past design decisions.'

Replace generic verbs with concrete actions, e.g. 'Draft, review, and supersede ADRs from templates, track decision status, and maintain an ADR index.'

Include common synonyms users might say, such as 'design decisions' and 'technical trade-offs', to improve trigger coverage.

Dimension	Reasoning	Score
Specificity	It names the ADR domain and concrete actions ('creating, maintaining, and managing'), but these are high-level verbs rather than a comprehensive list of specific operations, so it sits at the 'names domain and 1-2 concrete actions' anchor.	3 / 5
Completeness	It has a clear 'what' (comprehensive patterns for creating/maintaining ADRs) but no explicit 'Use when...' clause, which the guidelines say caps completeness at 3.	3 / 5
Trigger Term Quality	'Architecture Decision Records' and 'ADR' plus 'significant technical decisions' and 'technology choices' are natural phrases a user would say, but it omits common synonyms like 'design decisions' and 'technical trade-offs', leaving a few natural terms missing.	4 / 5
Distinctiveness Conflict Risk	The ADR niche is fairly distinct from most skills and the term 'Architecture Decision Records' is specific, though 'documenting technology choices' has minor overlap with general documentation skills.	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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/skills/architecture-decision-records/SKILL.md
Commit: debb2ec

Reviewed: 24 hours 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.