sdd-design
Create the SDD technical design and architecture approach. Trigger: orchestrator launches design for a change.
47
51%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./internal/assets/skills/sdd-design/SKILL.mdQuality
Discovery
25%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is too vague and relies on internal jargon ('orchestrator launches design') rather than natural user language. It fails to enumerate specific actions involved in creating an SDD and does not provide user-facing trigger terms. The acronym 'SDD' is never expanded, reducing discoverability.
Suggestions
Expand 'SDD' (System Design Document) and list concrete actions such as 'define system components, specify API contracts, document data models, create architecture diagrams'.
Replace the orchestrator-centric trigger with user-facing language, e.g., 'Use when the user asks for a system design document, technical architecture, or design specification for a change or feature'.
Add natural trigger terms users would say, such as 'system design', 'architecture document', 'technical specification', 'design doc'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description is vague — 'technical design and architecture approach' does not list concrete actions. It doesn't specify what creating an SDD entails (e.g., defining components, writing API contracts, producing diagrams). | 1 / 3 |
Completeness | It partially answers 'what' (create an SDD) and has a trigger clause, but the trigger is about an internal orchestrator rather than user-facing scenarios. The 'when' is not useful for matching user intent. | 2 / 3 |
Trigger Term Quality | The trigger terms are internal/technical jargon ('orchestrator launches design for a change') rather than natural keywords a user would say. Terms like 'SDD' are unexpanded and niche; no common user-facing synonyms are provided. | 1 / 3 |
Distinctiveness Conflict Risk | 'Design and architecture approach' is somewhat specific to SDD documents, but 'technical design' is broad enough to overlap with other architecture or design-related skills. The acronym 'SDD' helps somewhat but is not expanded. | 2 / 3 |
Total | 6 / 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 executor skill with strong actionability and clear workflow sequencing. The multi-mode persistence logic is handled cleanly, and the design document template provides concrete, copy-paste-ready structure. The main weaknesses are moderate verbosity (the full template inline inflates the token cost) and the inability to verify referenced shared files, though the references themselves are well-signaled.
Suggestions
Consider extracting the full design document template to a separate reference file (e.g., `design-template.md`) to reduce the inline token footprint and improve conciseness.
The persistence contract section repeats mode-specific logic that may already be covered in `sdd-phase-common.md` — consider consolidating to avoid duplication.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some redundancy — the persistence contract section partially repeats what's in the shared phase-common reference, and the full design document template is quite lengthy. The orchestrator gate preamble and mode-specific branching add necessary but verbose conditional logic. Some tightening is possible (e.g., the template could be more compact). | 2 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: exact file paths, a complete markdown template for the design document, specific artifact keys for persistence, a structured return envelope format, and clear rules. Each step tells the executor precisely what to do with specific outputs expected. | 3 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced (Load Skills → Read Codebase → Write Design → Persist Artifact → Return Summary) with explicit mandatory gates ('This step is MANDATORY — do NOT skip it'). The mode-conditional branching (engram/openspec/hybrid/none) is clearly laid out with specific instructions per mode. The rules section adds validation constraints like the 800-word budget and blocking-question escalation. | 3 / 3 |
Progressive Disclosure | The skill references shared files (`skills/_shared/sdd-phase-common.md`, `skills/_shared/openspec-convention.md`, `openspec/config.yaml`) with clear section callouts (Section A, B, C, D), which is good one-level-deep referencing. However, no bundle files were provided to verify these references exist, and the inline design template is quite long — it could arguably be extracted to a separate reference file. The structure is reasonable but the main file carries a lot of inline content. | 2 / 3 |
Total | 10 / 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 |
|---|---|---|
metadata_field | 'metadata' should map string keys to string values | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- sergiodvillegas-art/gentle-ai
- Commit
3bfa934
- 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.