CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architecture-decision-records

Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.

Quality

76%

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 ./skills/architecture-decision-records/SKILL.md

The canonical home for this skill is architecture-decision-records in affaan-m/ECC

SKILL.md
Quality
Evals
Security

Quality

Content

81%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 two clearly sequenced workflows, consent checkpoints, a complete template, and exact file conventions. Its main weakness is token efficiency — several sections explain standard ADR practice Claude already knows — and at 173 lines it could move reference material into a separate file.

Suggestions

Trim or cut the 'Categories of Decisions' table and 'ADR Lifecycle' section — this is standard Nygard ADR knowledge Claude already has — and keep only project-specific guidance.

Tighten 'What Makes a Good ADR' to the few rules that are specific to this skill (2-minute read length, marking backfilled dates) rather than general ADR best practice.

Consider moving the full ADR template and index format into a references file (e.g., references/template.md) with a pointer from the body, reducing the always-loaded body to the workflows and activation triggers.

DimensionReasoningScore

Conciseness

The workflow, template, and index sections are project-specific and earn their tokens, but 'What Makes a Good ADR', the 'Categories of Decisions' table, and 'ADR Lifecycle' largely restate the standard Nygard ADR practice Claude already knows. This is 'mostly efficient but includes some unnecessary explanation' rather than the minor-trimming case at 4.

3 / 5

Actionability

The skill provides a complete copy-paste ADR template, exact file paths and naming scheme ('docs/adr/NNNN-decision-title.md'), a concrete index format, and literal fallback responses ('No ADRs found in this project. Would you like to start recording architectural decisions?'). As an instruction-only skill, its guidance is fully executable.

5 / 5

Workflow Clarity

Both workflows are numbered with explicit validation checkpoints: 'Do not create files without explicit consent', 'present the draft ADR to the user for review. Only write... after explicit approval. If the user declines, discard the draft without writing any files.' The approval loop is exactly the right validation for a file-creating skill, and no destructive/batch cap applies.

5 / 5

Progressive Disclosure

A single well-organized file with clear section headers and no nested references, and every path referenced in the body is one the skill itself creates. At 173 lines, though, it exceeds the simple-skill exception, and content like the full ADR template and categories table could be split into a reference file, keeping it at 'good structure; minor organization gaps' rather than 5.

4 / 5

Total

17

/

20

Passed

Description

63%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 specific, action-oriented description in proper third-person voice that clearly conveys what the skill does, but it lacks any 'when to use' trigger guidance. Adding a 'Use when...' clause with natural user phrases ('why did we choose', 'record this decision', 'ADR this') would raise both completeness and trigger term quality.

Suggestions

Add an explicit 'Use when...' clause (e.g., 'Use when the user mentions ADRs, asks why an architectural choice was made, or decides between frameworks, databases, or API designs') to satisfy the completeness requirement.

Include natural trigger phrases users would actually say — 'why did we choose X', 'record this decision', 'ADR this', 'architectural trade-off' — to improve trigger term coverage.

Clarify the auto-detection behavior to avoid over-claiming, since the skill body requires user confirmation before creating any ADR.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — 'Capture architectural decisions... as structured ADRs', 'Auto-detects decision moments', 'records context, alternatives considered, and rationale', 'Maintains an ADR log' — comprehensively covering the skill's scope. All actions are explicitly stated, matching the comprehensive-coverage anchor rather than the minor-gaps anchor at 4.

5 / 5

Completeness

The 'what' is clear (capture decisions as structured ADRs, maintain a log), but there is no 'Use when...' clause or equivalent explicit trigger guidance, capping this dimension at 3 per the judging guidelines. It sits above the score-2 anchor because the 'what' is concrete and multi-part rather than vague.

3 / 5

Trigger Term Quality

Relevant keywords are present ('architectural decisions', 'ADRs', 'decision', 'rationale') but common natural phrases users would say — 'why did we choose X', 'record this decision', 'ADR this' — are absent. This matches 'some relevant keywords but missing common variations or synonyms' rather than the good coverage at 4.

3 / 5

Distinctiveness Conflict Risk

'Architectural decisions' and 'ADRs' carve a clear niche with low confusion risk against most skills, though overlap is possible with general documentation or memory-keeping skills. Not 5 because no explicit trigger phrases distinguish it from those near neighbors.

4 / 5

Total

15

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

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

Warning

relative_links

Relative link issues: 3 missing

Warning

Total

14

/

16

Passed

Repository

valeriibeck-star/claude-skills

Path

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.