CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architecture-decision-records

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

64

Quality

81%

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

SKILL.md
Quality
Evals
Security

Quality

Content

86%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.md body is an efficient, highly actionable operational guide: concrete directory and index templates, executable adr-tools commands, and phase-gated review checklists, with bulky templates correctly offloaded to clearly signaled one-level-deep reference files. Remaining improvements are minor: trim the introductory concept explanations and consolidate the creation-to-acceptance flow into a single sequenced workflow with an explicit feedback loop.

DimensionReasoningScore

Conciseness

The body is dominated by terse, high-value material — decision tables, a directory tree, a fill-in README/index template, executable commands, and checklists. Minor trimming is possible in the "What is an ADR?" section and the status-lifecycle diagram, which restate concepts Claude already knows, matching anchor 4's "efficient with minor instances of over-explanation" rather than anchor 5's every-token-earns-its-place.

4 / 5

Actionability

Guidance is fully executable and copy-paste ready: concrete directory structure, a complete ADR-index README template, adr-tools commands ("adr init docs/adr", "adr new -s 3", "adr generate toc", "adr link"), a 4-step manual creation flow, and phase-organized review checklists. The common cases — create, supersede, index, review — are all covered with specific commands or steps.

5 / 5

Workflow Clarity

A clear sequence exists (copy template → fill in → submit PR → review → update index after approval) with checkpoints supplied by the Before/During/After review checklists, matching anchor 4. It falls short of anchor 5 because there is no explicit error-recovery feedback loop (e.g. what to do when review rejects the ADR) and the end-to-end workflow must be assembled from fragments across sections rather than one canonical flow.

4 / 5

Progressive Disclosure

Verified against the actual bundle: both body references (references/decision-templates.md and references/deprecation-rfc-templates.md) exist as real files, are clearly signaled with routing conditions ("Before drafting a standard, lightweight, or Y-statement ADR, read [decision templates]..."), and are exactly one level deep (they contain only templates, no nested references). Heavy template content is correctly split out of SKILL.md, which stays a navigable overview.

5 / 5

Total

18

/

20

Passed

Description

70%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.

A solid description that clearly identifies its niche (ADRs), uses third person, and pairs a concrete what with an explicit, multi-scenario Use-when clause. Its main weakness is that the what-clause lists only two concrete actions and leans on generic "best practices" filler, costing it specificity and top-tier completeness.

Suggestions

Replace "following best practices for technical decision documentation" with concrete additional actions, e.g. "Write and maintain Architecture Decision Records (ADRs): draft records with context, decision, and consequences; manage status lifecycle (proposed, accepted, superseded); maintain the ADR index".

Add natural trigger synonyms users actually say, such as "design decisions", "technology choices", or "decision log", to the Use-when clause.

DimensionReasoningScore

Specificity

The description names the domain and two concrete actions ("Write and maintain Architecture Decision Records (ADRs)"), but "following best practices for technical decision documentation" is generic filler rather than additional specific actions, matching the anchor for domain plus 1-2 concrete actions without comprehensive coverage. It is not a 4 because it does not list several distinct specific actions.

3 / 5

Completeness

Both what ("Write and maintain Architecture Decision Records (ADRs)") and when ("Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes") are present and explicit, with three concrete trigger scenarios. It sits between anchors 4 and 5 rather than clearly at 5 because the what-clause is padded with "following best practices" instead of concrete action coverage.

4 / 5

Trigger Term Quality

Good natural keyword coverage: "Architecture Decision Records", "ADRs", "documenting significant technical decisions", "reviewing past architectural choices", "establishing decision processes" — phrases a user would plausibly say. It falls short of anchor 5 because common variations like "design decisions", "technology choices", or "decision log" are missing.

4 / 5

Distinctiveness Conflict Risk

"Architecture Decision Records (ADRs)" carves out a clear niche with distinctive terminology, but the broader triggers ("establishing decision processes", "documenting significant technical decisions") create minor overlap risk with general documentation or decision-making skills, matching anchor 4 rather than the minimal-conflict anchor 5.

4 / 5

Total

15

/

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

relative_links

Relative link issues: 4 missing

Warning

Total

15

/

16

Passed

Repository

wshobson/agents

Path

plugins/documentation-generation/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.