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.
77
77%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
67%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 does a strong job of specifying concrete capabilities and occupying a distinct niche around Architecture Decision Records. Its main weakness is the lack of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill. The trigger terms could also be broadened to include more natural user phrasings beyond the ADR acronym.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about documenting architecture decisions, recording design rationale, creating ADRs, or understanding why past decisions were made.'
Include additional natural trigger terms such as 'design decision', 'decision log', 'architecture decision record', 'why was this approach chosen', and 'document rationale' to improve discoverability.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: capture architectural decisions, auto-detect decision moments, record context/alternatives/rationale, and maintain an ADR log. These are clear, actionable capabilities. | 3 / 3 |
Completeness | The 'what' is well-covered with specific capabilities, but there is no explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied through the description of what it does, which per the rubric caps completeness at 2. | 2 / 3 |
Trigger Term Quality | Includes good terms like 'ADR', 'architectural decisions', 'rationale', and 'alternatives considered', but misses common user phrasings like 'architecture decision record', 'design decision', 'document why', or 'decision log'. Users might not naturally say 'ADR' if they don't know the acronym. | 2 / 3 |
Distinctiveness Conflict Risk | ADRs (Architecture Decision Records) are a very specific niche. The description clearly targets structured architectural decision documentation, which is unlikely to conflict with general documentation, code review, or other development skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted skill with strong actionability and workflow clarity — the step-by-step processes include proper confirmation gates and error handling paths. Its main weakness is moderate verbosity: sections like the categories table, ADR lifecycle explanation, and do/don't lists add bulk that Claude could infer or that could be moved to a reference file. The content is safe and well-bounded with explicit user consent requirements throughout.
Suggestions
Move the 'Categories of Decisions Worth Recording' table and 'What Makes a Good ADR' do/don't lists into a separate reference file (e.g., docs/adr/GUIDELINES.md) to reduce the main skill's token footprint.
Trim the ADR template by removing the italicized guidance text ('What is the issue that we're seeing...') — Claude can fill these sections based on the field names alone.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-structured but includes some unnecessary content that Claude already knows — the 'What Makes a Good ADR' do/don't list, the categories table, and the lifecycle explanation are somewhat verbose. The ADR format template includes placeholder commentary ('What is the issue...', 'What is the change...') that adds bulk without value. | 2 / 3 |
Actionability | The skill provides a concrete, copy-paste-ready ADR template, a specific directory structure, a concrete index format, explicit detection signals, and clear step-by-step workflows for both creating and reading ADRs. The guidance is specific and directly executable. | 3 / 3 |
Workflow Clarity | Both the 'Capturing a New ADR' and 'Reading Existing ADRs' workflows are clearly sequenced with numbered steps. Importantly, there are explicit confirmation/validation checkpoints — step 1 requires user confirmation before creating directories, step 7 requires explicit approval before writing, and the reading workflow has clear branching for missing ADRs. The implicit signals section explicitly states 'do not auto-create without user confirmation.' | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers, but it's a fairly long monolithic document (~150 lines of substantive content). The categories table, lifecycle section, and 'What Makes a Good ADR' guidelines could be split into a reference file. The brief 'Integration with Other Skills' section at the end is appropriately concise, but overall the skill inlines content that could benefit from separation. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents