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-claude/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 body is highly actionable with concrete templates, commands, and checklists, but it is noticeably verbose and inlines five full worked examples and management material that would be better split into referenced bundle files.

Suggestions

Move the five full ADR templates into separate reference files (e.g. references/templates/) and leave concise skeletons inline, pointing to the files for the worked prose.

Trim the narrative pros/cons/rationale inside each template example to reduce token padding while keeping the structure.

Add an explicit validation checkpoint to the core Instructions workflow (e.g. 'Review against the ADR checklist before submission').

Dimension	Reasoning	Score
Conciseness	The ~436-line body inlines five fully worked ADR examples with narrative pros/cons and rationale prose that goes well beyond what a template requires, adding noticeably verbose padding even though it does not over-explain basic concepts Claude already knows.	2 / 5
Actionability	Provides copy-paste-ready markdown ADR templates, concrete adr-tools commands ('brew install adr-tools', 'adr new -s 3 ...'), a directory layout, and a review checklist that fully cover the common cases.	5 / 5
Workflow Clarity	Multi-step processes are clearly sequenced (4-step Instructions, 4-phase migration plan, before/during/after review checklists) with most checkpoints present; the main write workflow lacks an explicit validation gate, but ADR authorship is not a destructive/batch operation so no cap applies.	4 / 5
Progressive Disclosure	Section headers give the body good structure, but all five templates and management material are inlined in SKILL.md with no bundle files (references/, scripts/, assets/ are empty) and no one-level-deep references, so content that should live in separate files is inline.	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 conveys the skill's domain and purpose with natural ADR terminology, but lacks an explicit 'when to use' trigger clause and relies on generic process verbs rather than a comprehensive list of concrete actions.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers, e.g. 'Use when making significant architectural decisions, adopting a framework, or recording design trade-offs.'

Replace abstract verbs with concrete deliverables, e.g. 'Drafts ADRs, links superseded decisions, and maintains the ADR index.'

Include common synonyms such as 'design decisions' and 'decision logs' to broaden natural trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the ADR domain and a few actions ('creating, maintaining, and managing'), but these are abstract process verbs framed as 'patterns for' rather than concrete, enumerative operations, fitting the 1-2-concrete-actions anchor more than the comprehensive-coverage anchor.	3 / 5
Completeness	Has a clear 'what' (patterns for creating/maintaining/managing ADRs that capture context and rationale) but no explicit 'Use when...' trigger clause; per the rubric a missing trigger clause caps completeness at 3.	3 / 5
Trigger Term Quality	Includes natural domain terms ('Architecture Decision Records', 'ADRs', 'technical decisions', 'context and rationale') that users would say, but misses common synonyms like 'design decisions' or 'decision logs', so coverage is good rather than comprehensive.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear, distinct niche (Architecture Decision Records / ADRs) unlikely to fire for the wrong skill, with only minor overlap risk against generic 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-claude/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.