Create technical design document with architecture decisions and approach. Trigger: "design", "diseño técnico", "technical design", "architecture", "diseñar", "sdd design", "/sdd:continue (when specs exist but design doesn't)".
83
79%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./ywai/skills/sdd-design/SKILL.mdQuality
Discovery
82%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 has strong trigger term coverage with bilingual support and an explicit trigger clause, making it complete. However, the capability description is somewhat generic ('architecture decisions and approach') and some trigger terms like 'design' and 'architecture' are broad enough to potentially conflict with other skills.
Suggestions
Add more specific concrete actions like 'define system components, document API contracts, create architecture diagrams, record design trade-offs'
Narrow the broad triggers by adding qualifiers, e.g., 'software architecture' or 'system design' to reduce conflict with UI/UX design skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (technical design documents) and mentions 'architecture decisions and approach' but lacks specific concrete actions like 'create diagrams', 'define interfaces', or 'document trade-offs'. | 2 / 3 |
Completeness | Explicitly answers both what ('Create technical design document with architecture decisions and approach') and when (via 'Trigger:' clause with multiple explicit trigger terms and a conditional use case). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms including English ('design', 'technical design', 'architecture') and Spanish variations ('diseño técnico', 'diseñar'), plus command syntax ('/sdd:continue'). These are terms users would naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | While 'technical design document' and 'sdd' are fairly specific, terms like 'design' and 'architecture' are broad and could conflict with UI design, system architecture, or general software design skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured skill with excellent actionability and workflow clarity. The step-by-step process is clear, error recovery is comprehensive, and the output format is concrete and executable. The main weakness is verbosity in the template section, which could be more concise while maintaining clarity.
Suggestions
Consider moving the full design document template to a separate reference file (e.g., DESIGN_TEMPLATE.md) and keeping only a condensed example in the main skill
The Mermaid diagram example could be shortened or moved to a reference file since Claude knows Mermaid syntax
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some verbose template sections (like the full Mermaid diagram example and extensive table templates) that could be condensed. The document format section is comprehensive but lengthy. | 2 / 3 |
Actionability | Provides fully concrete guidance with specific file paths, exact markdown templates, code blocks for diagrams, and clear table formats. The steps are executable and copy-paste ready with specific persistence commands. | 3 / 3 |
Workflow Clarity | Clear 4-step sequence (Read Codebase → Write design.md → Persist → Return Summary) with explicit validation through the Error Recovery table. Includes feedback loops for blocked states and scope creep detection. | 3 / 3 |
Progressive Disclosure | References external files appropriately (persistence-contract.md, engram-convention.md, openspec-convention.md) but the main document is quite long. The design template could potentially be split into a separate reference file. | 2 / 3 |
Total | 10 / 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 |
|---|---|---|
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 10 / 11 Passed | |
d9bf9a4
Table of Contents
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.