sdd-design
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
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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, it lacks specificity in describing concrete actions beyond 'create' and uses somewhat generic terms like 'design' and 'architecture' that could cause conflicts with other design-related skills.
Suggestions
Add more specific concrete actions like 'define component interactions, document API contracts, create sequence diagrams, specify data models'
Narrow the trigger terms to reduce conflict risk - consider prefixing generic terms like 'SDD design' or 'technical design document' rather than just 'design' or 'architecture'
| 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 API contracts', or 'document data models'. | 2 / 3 |
Completeness | Clearly answers both what ('Create technical design document with architecture decisions and approach') and when (explicit 'Trigger:' clause with multiple trigger terms and a conditional scenario for /sdd:continue). | 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 somewhat 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. However, the extensive inline template adds verbosity that could be externalized, and some sections explain patterns that could be more concise.
Suggestions
Consider moving the full design.md template to a separate DESIGN-TEMPLATE.md file and referencing it, keeping only a brief example in the main skill
Condense the Mermaid diagram example - showing both Mermaid and ASCII fallback is verbose; a brief note about preference with one example would suffice
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some verbose template sections (like the full Mermaid diagram example and extensive table templates) that could be condensed. The format templates are useful but add significant length. | 2 / 3 |
Actionability | Provides fully concrete guidance with specific file paths, exact markdown templates, code examples (Mermaid diagrams), and clear table formats. The step-by-step process is copy-paste ready with specific commands for persistence modes. | 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 handling conflicts, scope creep, and blocking questions. | 3 / 3 |
Progressive Disclosure | References external files appropriately (persistence-contract.md, engram-convention.md, openspec-convention.md) but the main content is a large monolithic template. The design document format section could 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 | |
- 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.