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.
85
81%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
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.
This is an excellent skill description that hits all the marks. It provides specific capabilities, rich natural trigger terms, explicit 'Use when' and 'Do NOT use when' clauses, and clear differentiation from related skills. The inclusion of alternative skill references for boundary cases is a best practice that makes this description particularly effective for skill selection.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lists a concrete action ('Creates Architecture Decision Records (ADRs) to document significant architectural choices and their rationale') and specifies the purpose ('for future team members'). It clearly names the artifact being produced and its intent. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates ADRs to document architectural choices and rationale) and 'when' (explicit 'Use when' clause with multiple trigger phrases). Additionally includes 'Do NOT use when' guidance with references to alternative skills, which further strengthens completeness. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger phrases: 'write an ADR', 'document this decision', 'record why we chose X', 'add an architecture decision record', 'create an ADR for', and the broader 'capture the reasoning behind a technical choice'. These are phrases users would naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with clear boundaries. The description explicitly differentiates from related skills (create-rfc for unmade decisions, technical-design-doc-creator for implementation planning) and excludes general documentation. The ADR niche is well-defined and unlikely to conflict. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with excellent templates and a clear multi-step workflow with validation checkpoints. However, it is significantly over-verbose — explaining concepts Claude already understands (ADR vs RFC distinctions, what immutability means, basic writing advice), repeating guidance across sections, and including unnecessary example prompts. The content would be substantially improved by cutting 40-50% of the text and splitting templates into referenced files.
Suggestions
Remove the 'When to Use This Skill' section and 'ADR vs RFC' comparison table — this duplicates the frontmatter description and explains distinctions Claude can infer from context.
Move the three document templates into a separate TEMPLATES.md file referenced from the main skill, keeping only the default MADR template inline.
Remove the 'Example Prompts that Trigger This Skill' section entirely — trigger detection is handled by the frontmatter description and Claude's inference.
Consolidate the 'Common Anti-Patterns', 'Important Notes', and 'ADR Quality Checklist' into a single concise checklist, eliminating redundant guidance repeated across these sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~350+ lines. It explains concepts Claude already knows (what an ADR is, what immutability means, the difference between ADRs and RFCs), includes extensive anti-pattern examples that restate obvious writing advice, provides example prompts in three languages that duplicate the frontmatter description, and repeats guidance across multiple sections (e.g., 'Important Notes' restates points already covered in templates and anti-patterns). | 1 / 3 |
Actionability | The skill provides fully concrete, copy-paste-ready templates for all three ADR formats (MADR, Nygard, Y-Statement), specific file naming conventions, a structured AskQuestion JSON payload, and explicit step-by-step workflows with exact commands and directory paths. | 3 / 3 |
Workflow Clarity | The 5-step interactive workflow is clearly sequenced with explicit validation (Step 2 validates mandatory fields, the quality checklist serves as a final verification gate). The workflow includes feedback loops (ask if missing fields) and clear decision points (format selection, file placement). | 3 / 3 |
Progressive Disclosure | The content has good section structure with headers, but everything is inlined in a single monolithic file. The three full templates, extensive anti-patterns section, and example prompts could be split into referenced files. The skill would benefit from a concise overview pointing to separate template and examples files. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- tech-leads-club/agent-skills
- Commit
81e7e0d
- 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.