design-doc-template
Design Doc Template - Auto-activating skill for Technical Documentation. Triggers on: design doc template, design doc template Part of the Technical Documentation skill category.
36
3%
Does it follow best practices?
Impact
100%
1.00xAverage 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/design-doc-template/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 thin and formulaic, providing almost no information about what the skill actually does beyond its name. It lacks concrete actions, meaningful trigger terms, and any explicit 'Use when...' guidance. It would be very difficult for Claude to confidently select this skill from a pool of similar documentation-related skills.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Generates a structured design document template with sections for problem statement, proposed solution, alternatives considered, and implementation plan.'
Add an explicit 'Use when...' clause with natural trigger variations, e.g., 'Use when the user asks for a design doc, design document, technical design template, RFC, architecture proposal, or spec outline.'
Remove the duplicate trigger term ('design doc template' is listed twice) and expand with natural keyword variations users would actually say.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names no concrete actions. It says 'Auto-activating skill for Technical Documentation' but never specifies what it actually does—no mention of creating, filling, formatting, or reviewing design documents. | 1 / 3 |
Completeness | The 'what' is essentially absent (no concrete capabilities described) and the 'when' is only a redundant trigger phrase with no explicit 'Use when...' clause or meaningful guidance on activation conditions. | 1 / 3 |
Trigger Term Quality | The only trigger terms listed are 'design doc template' repeated twice. There are no natural variations a user might say such as 'design document', 'technical design', 'architecture doc', 'RFC template', or 'spec template'. | 1 / 3 |
Distinctiveness Conflict Risk | The phrase 'design doc template' is somewhat specific to a niche (design document templates), which reduces conflict with generic documentation skills. However, the lack of detail about what it does versus other documentation skills still leaves moderate overlap risk. | 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 essentially a placeholder with no substantive content. It repeatedly describes itself in abstract terms without providing any actual design doc template, concrete guidance, examples, or actionable instructions. It fails on every dimension because it contains no real skill content—only meta-descriptions of what a skill could theoretically do.
Suggestions
Replace the abstract descriptions with an actual design doc template structure (e.g., sections like Problem Statement, Proposed Solution, Alternatives Considered, etc.) with brief guidance for each section.
Add a concrete, copy-paste-ready markdown template that Claude can use directly when a user asks for a design doc template.
Include at least one worked example showing a filled-in design doc template for a realistic scenario.
Remove all the meta-content about triggers, capabilities, and when-to-use sections—these belong in frontmatter, not in the skill body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is almost entirely filler and meta-description. It explains what the skill does in abstract terms without providing any actual template, instructions, or actionable content. Every section restates the same vague idea. | 1 / 3 |
Actionability | There is zero concrete guidance—no template structure, no example design doc sections, no commands, no code, no specific instructions. It only describes what it could do rather than doing it. | 1 / 3 |
Workflow Clarity | No workflow, steps, or process is defined. The skill claims to provide 'step-by-step guidance' but contains none. There are no validation checkpoints or sequenced actions. | 1 / 3 |
Progressive Disclosure | The content is a monolithic block of vague descriptions with no references to supporting files, no structured navigation, and no separation of overview from detail. There are no bundle files to reference either, but the content itself lacks any organizational structure. | 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
3a2d27d
- 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.