adr-generator
Adr Generator - Auto-activating skill for Technical Documentation. Triggers on: adr generator, adr generator Part of the Technical Documentation skill category.
36
3%
Does it follow best practices?
Impact
100%
1.02xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./planned-skills/generated/17-technical-docs/adr-generator/SKILL.mdQuality
Discovery
7%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 description is extremely minimal and template-like, providing almost no useful information for skill selection. It fails to describe what the skill actually does (e.g., generating Architecture Decision Records), lacks natural trigger terms users would say, and has no explicit 'when to use' guidance. The only slight positive is that 'ADR' is a somewhat distinctive term.
Suggestions
Add concrete actions describing what the skill does, e.g., 'Generates Architecture Decision Records (ADRs) from technical discussions, including status, context, decision, and consequences sections.'
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to create an ADR, document an architecture decision, record a technical decision, or generate a decision log.'
Include common keyword variations users might say: 'ADR', 'architecture decision record', 'decision record', 'technical decision documentation', 'decision log'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description provides no concrete actions. It only states 'Auto-activating skill for Technical Documentation' without describing what it actually does—no mention of creating, formatting, reviewing, or managing ADRs. | 1 / 3 |
Completeness | Neither the 'what' nor the 'when' is adequately addressed. There is no explanation of what the skill does beyond its name, and no explicit 'Use when...' clause or equivalent trigger guidance. | 1 / 3 |
Trigger Term Quality | The only trigger terms listed are 'adr generator' repeated twice. It misses natural user phrases like 'architecture decision record', 'ADR', 'document architecture decisions', 'decision log', or 'technical decision'. | 1 / 3 |
Distinctiveness Conflict Risk | The term 'ADR Generator' is somewhat niche and specific to architecture decision records, which provides some distinctiveness. However, the vague 'Technical Documentation' category label could overlap with many other documentation skills. | 2 / 3 |
Total | 5 / 12 Passed |
Implementation
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is an empty placeholder with no actual content. It contains only meta-descriptions of what it claims to do without any ADR templates, examples, commands, or actionable instructions. It provides zero value for generating Architecture Decision Records.
Suggestions
Add a concrete ADR template in markdown format (e.g., with sections for Title, Status, Context, Decision, Consequences) that Claude can directly use to generate ADRs.
Include at least one complete example of a generated ADR so Claude understands the expected output format and quality.
Provide a clear workflow: 1) Gather context from user, 2) Select appropriate ADR number/naming, 3) Fill template, 4) Validate required sections are present, 5) Write to file.
Remove all the generic meta-sections (When to Use, Example Triggers, Capabilities) that describe the skill abstractly and replace them with actual actionable content.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is entirely filler with no substantive information. It explains what the skill does in abstract terms without providing any actual guidance, commands, or templates for generating ADRs. Every section restates the same vague concept. | 1 / 3 |
Actionability | There is zero concrete, executable guidance. No ADR template, no commands, no example output, no file structure — nothing that would help Claude actually generate an Architecture Decision Record. | 1 / 3 |
Workflow Clarity | No workflow is defined at all. The skill claims to provide 'step-by-step guidance' but contains no steps. There is no sequence, no validation, and no process for creating ADRs. | 1 / 3 |
Progressive Disclosure | The content is a flat, repetitive structure with no meaningful organization. There are no references to external files, no layered content, and the sections are redundant rather than progressively informative. | 1 / 3 |
Total | 4 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
b8a3b3e
- 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.