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.
82
77%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./packages/skills-catalog/skills/(creation)/create-adr/SKILL.mdQuality
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 actions, comprehensive trigger terms users would naturally use, explicit 'Use when' and 'Do NOT use when' clauses, and clear differentiation from related skills. The negative boundary conditions referencing specific alternative skills are particularly effective for disambiguation.
| 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, making conflict with other skills very unlikely. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
55%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 workflow, but is severely bloated. It includes substantial content that Claude already knows (what ADRs are, general writing anti-patterns), redundant routing information (trigger phrases, ADR vs RFC distinction), and inlines content that should be in separate reference files (three full templates, anti-patterns). Cutting this to ~40% of its current length while extracting templates to separate files would dramatically improve it.
Suggestions
Extract the three ADR templates into a separate TEMPLATES.md file and reference it from the main skill, reducing the body by ~40%.
Remove the 'When to Use This Skill', 'ADR vs RFC', and 'Example Prompts' sections entirely — this routing logic belongs in the frontmatter description, not the skill body.
Remove or drastically condense the anti-patterns section — Claude already understands good writing principles like 'be specific' and 'include trade-offs'; a 2-line reminder suffices.
Remove explanatory framing like 'You are an expert in creating Architecture Decision Records' and the definition of what ADRs are — Claude knows this and the skill should jump straight to the workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. Includes extensive content Claude already knows: what ADRs are, the distinction between ADRs and RFCs (which belongs in the description/routing, not the body), example prompts that trigger the skill (redundant with frontmatter), explanations of anti-patterns that are general writing knowledge, and a full comparison table of ADR vs RFC. The templates alone would suffice with minimal framing. | 1 / 3 |
Actionability | Provides complete, copy-paste-ready templates for all three ADR formats (MADR, Nygard, Y-Statement), concrete JSON for the AskQuestion interaction, specific file naming conventions, and a detailed quality checklist. The guidance is highly specific and executable. | 3 / 3 |
Workflow Clarity | Clear 5-step sequential workflow (Gather Context → Validate Fields → Assign Number → Generate → Offer Placement) with explicit validation checkpoints (mandatory field validation in Step 2, quality checklist before finalizing). The ADR numbering step includes a concrete procedure for scanning existing directories. | 3 / 3 |
Progressive Disclosure | Monolithic wall of text with everything inline — three full document templates, anti-pattern examples, comparison tables, example prompts in three languages, and naming conventions all in a single file. The templates and anti-patterns sections should be in separate referenced files, and the example prompts section adds no value in the skill body. | 1 / 3 |
Total | 8 / 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
906a57d
- 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.