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).

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is highly actionable with a clear sequenced workflow and validation loops, but it is token-inefficient and monolithic: trilingual duplication, concept re-explanation, and 20 full templates crammed into one file inflate the context cost and bury the core guidance.

Suggestions

Move the 20 section templates into a separate reference file (e.g. references/TEMPLATES.md) and keep SKILL.md as a concise overview that links to it; this raises both conciseness and progressive_disclosure.

Drop the trilingual duplication: state the language-adaptation rule once and keep one English example per workflow step rather than repeating every prompt in EN/PT/ES, which is the largest source of padding.

Remove the 'Industry Standards Reference' and 'Example Prompts that Trigger This Skill' sections — Claude already knows these concepts and the description already carries the triggers — and cut the 'Common Anti-Patterns' section that re-states the templates.

Dimension	Reasoning	Score
Conciseness	The body is heavy with padding Claude does not need — trilingual duplication of workflow steps and trigger prompts (EN/PT/ES), an 'Industry Standards Reference' explaining Google/Amazon/RFC/ADR/OWASP concepts Claude already knows, and a 'Common Anti-Patterns' section that re-states the templates above. It retains useful template substance, so it is not a 1, but the verbosity keeps it off the lean/efficient anchor.	2 / 3
Actionability	Guidance is concrete and copy-paste ready: a full AskQuestion JSON payload, 20 complete markdown section templates, and explicit 'If user says X / If missing: Ask Y' fallback prompts that tell Claude exactly what to do at each branch.	3 / 3
Workflow Clarity	The Interactive Workflow is sequenced as Steps 1–6 with explicit validation checkpoints (Step 2 validates mandatory info, a Mandatory/Critical Section Checklist before finalizing) and 'If missing → ask' feedback loops. TDD generation is not a destructive or batch operation, so the missing-feedback-loop cap does not apply.	3 / 3
Progressive Disclosure	No bundle files exist and the entire skill is a monolithic ~1485-line SKILL.md; the 20 section templates, the header-translation table, and the anti-pattern/trigger examples are all inline when they belong in separate reference files. Internal sectioning is clear (so not a 1), but content that should be split out is inline, so it does not reach the well-signaled one-level-deep reference level.	2 / 3
	Total	10 / 12 Passed

Description

90%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, well-constructed description: explicit triggers, a clear what/when pair, and deliberate disambiguation from docs-writer. The only soft spot is specificity, since it names one primary action rather than enumerating several concrete capabilities.

Dimension	Reasoning	Score
Specificity	The description names the domain and core action concretely — 'Creates comprehensive Technical Design Documents (TDD) with mandatory and optional sections through interactive discovery' — but centers on a single verb rather than listing multiple distinct concrete actions, so it sits at the 'names domain and some actions' anchor rather than the multi-action level.	2 / 3
Completeness	It explicitly answers both 'what' (creates TDDs with mandatory/optional sections via interactive discovery) and 'when' (an explicit 'Use when user asks to...' clause with multiple triggers), so it clears the both-what-and-when bar.	3 / 3
Trigger Term Quality	It surfaces natural phrases users actually say — 'write a design doc', 'create a TDD', 'technical spec', 'architecture document', 'RFC', 'design proposal' — giving broad, natural coverage rather than jargon.	3 / 3
Distinctiveness Conflict Risk	The negative guidance — 'Do NOT use for README files, API docs, or general documentation (use docs-writer instead)' — carves out a clear niche and actively prevents conflict with the adjacent docs-writer skill.	3 / 3
	Total	11 / 12 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 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
referenced_paths_exist	Referenced path issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: tech-leads-club/agent-skills
Commit: 9026164

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.