Content
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a comprehensive ADR handbook than a focused skill for Claude. It is extremely verbose, explaining concepts Claude already understands and providing five full-length template examples inline rather than referencing external files. While the templates themselves are well-crafted and the adr-tools commands are actionable, the sheer volume of content undermines usability, and the workflow for Claude to actually follow when creating an ADR is buried under reference material.
Suggestions
Reduce to one primary template inline (e.g., Standard MADR) and move the other four templates to separate referenced files (e.g., templates/lightweight.md, templates/y-statement.md).
Remove the 'Core Concepts' section entirely—Claude already knows what ADRs are, their lifecycle, and when to write them.
Restructure the Instructions section into a clear, numbered workflow with explicit decision points (e.g., 'Determine template based on decision complexity', 'Verify all required sections are populated before submitting').
Move the Review Checklist, Best Practices, and ADR Management sections into a separate MANAGEMENT.md reference file, keeping only a brief summary with links in the main skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. Explains basic concepts Claude already knows (what an ADR is, when to write one, lifecycle states). Five full template examples with extensive prose content that could be replaced by a single template with brief annotations. The 'Core Concepts' section is entirely unnecessary for Claude. | 1 / 3 |
Actionability | Provides concrete templates and examples that are copy-paste ready, plus real CLI commands for adr-tools. However, the skill is more of a reference document than actionable instructions—it doesn't clearly tell Claude what to DO when asked to create an ADR (e.g., which template to pick, how to determine the next number, where to place the file). | 2 / 3 |
Workflow Clarity | The Instructions section lists 4 high-level steps but lacks specificity on sequencing and validation. The review checklist provides checkpoints but isn't integrated into the workflow. There's no feedback loop for validating the ADR content (e.g., check that all sections are filled, verify linked ADRs exist). The 'Creating a New ADR' steps in the index section are clearer but buried deep in the document. | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files despite having five full templates that should be separate files. Everything is inline—templates, examples, management guidelines, review checklists, best practices—making it extremely long. No bundle files exist to offload content to, and the skill doesn't attempt any structural separation. | 1 / 3 |
Total | 6 / 12 Passed |