technical-design-doc-creator
Creates comprehensive Technical Design Documents (TDD) with mandatory and optional sections through interactive discovery. Use when user asks to "write a design doc", "create a TDD", "technical spec", "architecture document", "RFC", "design proposal", or needs to document a technical decision before implementation. Do NOT use for README files, API docs, or general documentation (use docs-writer instead).
81
77%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./packages/skills-catalog/skills/(creation)/create-technical-design-doc/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 clearly states what the skill does, provides comprehensive trigger terms users would naturally use, explicitly defines when to use it and when not to, and even redirects to an alternative skill for related but distinct tasks. The negative boundary clause is a particularly strong feature for reducing conflict risk.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists concrete actions ('Creates comprehensive Technical Design Documents') and specifies the approach ('mandatory and optional sections through interactive discovery'). It also clarifies what it does NOT do, adding further specificity. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates TDDs with mandatory/optional sections through interactive discovery) and 'when' (explicit 'Use when' clause with multiple trigger phrases). Also includes a 'Do NOT use' clause for disambiguation, which goes above and beyond. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms: 'write a design doc', 'create a TDD', 'technical spec', 'architecture document', 'RFC', 'design proposal', and 'document a technical decision before implementation'. These are terms users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with explicit negative boundary ('Do NOT use for README files, API docs, or general documentation') and a redirect to an alternative skill ('docs-writer'). The trigger terms are specific to technical design documents, minimizing conflict risk. | 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.
This skill is extremely thorough and actionable with excellent workflow clarity and validation checkpoints, but it is massively over-engineered for a SKILL.md file. At 800+ lines with all 20 section templates fully inlined, translation tables, glossary definitions of basic acronyms, and extensive anti-pattern examples, it wastes enormous context window space. The content would be far more effective as a concise overview with templates split into referenced files.
Suggestions
Extract section templates 8-20 into a separate TEMPLATES.md file and reference it from the main skill, keeping only the mandatory sections (1-7) inline with brief descriptions of others.
Remove the translation table and language-specific prompt examples - instead provide a single concise instruction like 'Match the user's language for all headers and prose; keep technical terms in English.'
Remove explanations of well-known concepts (what GDPR is, what an API is, what PCI DSS stands for) and the glossary template that defines basic acronyms.
Consolidate the 'High-Level vs Implementation Details' section to just the guideline question ('Will this change if we switch frameworks?') and one good/bad example pair, removing the redundant tables and multiple examples.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~800+ lines. Contains massive translation tables, extensive anti-pattern examples, full template content for all 20 sections, and explanations of concepts Claude already knows (what PCI DSS is, what a webhook is, what GDPR means). The glossary template literally defines 'API' as 'Application Programming Interface'. Most of this could be condensed to 20% of its size. | 1 / 3 |
Actionability | Highly actionable with concrete templates for every section, specific JSON structures for the AskQuestion tool, detailed table formats, example request/response payloads, and clear checklists. The interactive workflow steps are well-defined with specific tool usage patterns. | 3 / 3 |
Workflow Clarity | Clear 6-step interactive workflow with explicit validation checkpoints (Step 2 validates mandatory info, Step 3 checks critical sections based on project type, validation rules checklist at the end). Includes feedback loops for missing information and clear sequencing of the discovery process. | 3 / 3 |
Progressive Disclosure | Monolithic wall of text with all 20 section templates fully inlined. The full templates for suggested/optional sections (12-20) should be in separate reference files. The translation table, anti-patterns section, and example prompts all add bulk that could be externalized. No references to supplementary files. | 1 / 3 |
Total | 8 / 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 |
|---|---|---|
skill_md_line_count | SKILL.md is long (1485 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- tech-leads-club/agent-skills
- Commit
81e7e0d
- 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.