create-adr

Creates Architecture Decision Records (ADRs) to document significant architectural choices and their rationale for future team members. Use when the user says "write an ADR", "document this decision", "record why we chose X", "add an architecture decision record", "create an ADR for", or wants to capture the reasoning behind a technical choice so the team understands it later. Do NOT use when the decision hasn't been made yet (use create-rfc instead), for implementation planning (use technical-design-doc-creator), or for general documentation.

Quality

88%

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

Quality

Content

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

A comprehensive, well-organized ADR skill body with actionable templates and a clear workflow, quality checklist, and anti-pattern guidance. It is self-contained with no external references and could add an explicit validation gate in the generate workflow and optionally offload the format templates to reference files.

Suggestions

Add an explicit validation gate between Step 3 (assign number) and Step 4 (generate), e.g. 'Confirm the assigned number is unique and the mandatory fields are gathered before generating the ADR.'

Consider moving the three full format templates (MADR/Nygard/Y-Statement) into a references/ file (e.g. TEMPLATES.md) and summarizing each format inline in SKILL.md to improve token efficiency and progressive disclosure.

Tighten the Common Anti-Patterns section by trimming the BAD/GOOD code blocks to one illustrative line each, since Claude already understands the structural pattern once shown once.

Dimension	Reasoning	Score
Conciseness	The body is well-structured with minimal padding and avoids re-explaining concepts Claude already knows; the illustrative anti-pattern BAD/GOOD blocks are useful but slightly verbose, keeping it just below the lean/efficient anchor 5.	4 / 5
Actionability	It provides copy-paste-ready MADR, Nygard, and Y-Statement templates, a concrete AskQuestion JSON payload, a quality checklist, and explicit naming conventions — fully executable guidance covering common cases.	5 / 5
Workflow Clarity	Five sequenced steps with a quality checklist serving as a validation checkpoint; however the number-assignment (Step 3) and generation (Step 4) steps lack an explicit verify-before-proceeding gate, leaving minor validation gaps versus anchor 5.	4 / 5
Progressive Disclosure	The single-file body is organized into clearly headed sections (When to Use, Workflow, Templates, Checklist, Anti-Patterns) with appropriate inlining for a self-contained instruction skill and no nested references; it is not split into separate files, which would be needed for anchor 5.	4 / 5
	Total	17 / 20 Passed

Description

95%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 strong, well-structured description that concretely states what the skill does, when to use it with natural trigger phrases, and clearly distinguishes it from adjacent RFC and design-doc skills. Minor room only to enumerate more distinct concrete actions.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Creates Architecture Decision Records') and concrete actions ('document significant architectural choices and their rationale'), plus negative-case framing; it stops short of listing multiple distinct concrete actions, placing it between anchors 3 and 5.	4 / 5
Completeness	It explicitly answers both 'what' (creates ADRs documenting architectural choices and rationale for future team members) and 'when' with concrete trigger phrases, and adds explicit Do-NOT-use boundary guidance.	5 / 5
Trigger Term Quality	It provides comprehensive natural trigger phrases users would actually say — 'write an ADR', 'document this decision', 'record why we chose X', 'add an architecture decision record', 'create an ADR for' — including synonyms.	5 / 5
Distinctiveness Conflict Risk	It occupies a clear niche (ADRs) and explicitly disambiguates from named adjacent skills (create-rfc, technical-design-doc-creator) via a Do-NOT-use clause, minimizing conflict risk.	5 / 5
	Total	19 / 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
relative_links	Relative link issues: 3 missing	Warning

	Total	15 / 16 Passed

Repository: tech-leads-club/agent-skills
Path: packages/skills-catalog/skills/(creation)/create-adr/SKILL.md
Commit: fc886b7

Reviewed: 5 days 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.