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

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

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 complete templates and a clear, validated workflow, but it is verbose and monolithic — inline template/reference material and duplicated guidance could be split into reference files to improve token efficiency and progressive disclosure.

Suggestions

Move the three full ADR templates (MADR/Nygard/Y-Statement) into a reference file (e.g., references/templates.md) and link to it from a concise summary, reducing the SKILL.md body and improving progressive_disclosure.

Trim or remove the duplicated 'When to Use / Do NOT use' list and the ADR-vs-RFC explanation table, since the description already conveys triggers and the distinction can be stated in one line.

Condense the BAD/GOOD anti-pattern blocks into a compact checklist of pitfalls rather than multi-paragraph examples, to tighten conciseness without losing the guidance.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and accurate but includes redundant/teaching material that could be tightened: the ADR-vs-RFC table re-explains timing/purpose, the When-to-Use/Do-NOT-use list duplicates the description, and verbose BAD/GOOD anti-pattern blocks add tokens beyond what Claude needs; not score 3 because verbosity is present, not score 1 because it is not a padded concept primer.	2 / 3
Actionability	Provides three complete copy-paste-ready templates (MADR/Nygard/Y-Statement), a concrete AskQuestion JSON block, explicit file-naming examples, and specific directory paths — fully actionable, instruction-only guidance matching the score-3 anchor.	3 / 3
Workflow Clarity	Five clearly sequenced steps with an explicit mandatory-field validation gate in Step 2 ('ask if missing') and a finalizing quality checklist, matching the score-3 'clear sequence with explicit validation steps' anchor and exceeding the score-2 sequence-without-checkpoints level.	3 / 3
Progressive Disclosure	No bundle files exist and the body contains no external references; content is well-organized into sections but a large amount of template material is inline and monolithic (~420 lines) where some could be split into reference files, matching the score-2 'content that should be separate is inline' anchor rather than the score-3 one-level-deep-reference pattern.	2 / 3
	Total	10 / 12 Passed

Description

100%

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 is specific, uses natural third-person trigger phrases, explicitly states both what and when, and proactively disambiguates from sibling skills. It is a strong, well-scoped description with no meaningful weaknesses.

Dimension	Reasoning	Score
Specificity	Concrete artifact (ADRs) and multiple specific actions are named ('Creates', 'document... choices and their rationale'), matching the 'lists multiple specific concrete actions' anchor rather than the vague score-2 domain-only level.	3 / 3
Completeness	Explicitly answers what ('Creates Architecture Decision Records... to document... rationale') and when via an explicit 'Use when...' clause plus a 'Do NOT use when...' boundary, matching the score-3 both-answered anchor.	3 / 3
Trigger Term Quality	Quotes natural phrases users say ('write an ADR', 'document this decision', 'record why we chose X', 'create an ADR for') with good variation coverage, matching the score-3 anchor and exceeding the score-2 'some keywords' level.	3 / 3
Distinctiveness Conflict Risk	Clear ADR niche with a 'Do NOT use' clause that names sibling skills (create-rfc, technical-design-doc-creator) to avoid overlap, giving distinct triggers unlikely to conflict per the score-3 anchor.	3 / 3
	Total	12 / 12 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
Commit: 9026164

Reviewed: 4 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.