sdd-design
Create technical design document with architecture decisions and approach. Trigger: When the orchestrator launches you to write or update the technical design for a change.
68
60%
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 ./skills/sdd-design/SKILL.mdQuality
Discovery
35%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 identifies its core purpose (creating technical design documents) but lacks specificity in concrete actions and uses system-internal language ('orchestrator launches you') rather than natural user trigger terms. It would benefit from listing specific deliverables and using user-facing language for when the skill should be selected.
Suggestions
Replace the orchestrator-focused trigger with natural user language, e.g., 'Use when the user asks for a technical design document, design doc, TDD, architecture proposal, or system design writeup.'
Add more specific concrete actions, e.g., 'Creates technical design documents covering system architecture, component diagrams, API contracts, data models, trade-off analysis, and implementation approach.'
Include common file format or artifact references if applicable, e.g., 'Produces markdown design docs with sections for context, goals, architecture decisions, alternatives considered, and rollout plan.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (technical design documents) and mentions 'architecture decisions and approach' but doesn't list multiple concrete actions beyond 'create' and implicitly 'update'. It's somewhat specific but not comprehensive. | 2 / 3 |
Completeness | The 'what' is present (create technical design document with architecture decisions). The 'when' clause exists but is framed around an orchestrator launching the skill rather than providing explicit user-facing triggers, making it weak as a selection guide. | 2 / 3 |
Trigger Term Quality | The trigger clause references 'the orchestrator launches you' which is internal/technical jargon, not natural user language. Terms like 'technical design', 'architecture decisions' are somewhat relevant but the trigger itself is system-oriented rather than user-oriented. Missing natural terms like 'design doc', 'TDD', 'architecture document', 'system design'. | 1 / 3 |
Distinctiveness Conflict Risk | It's somewhat specific to technical design documents, which narrows the domain, but 'architecture decisions and approach' could overlap with other documentation or planning skills. The lack of specific file types or distinct terminology reduces distinctiveness. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
85%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 that provides clear, actionable guidance for creating technical design documents. The workflow is well-sequenced with appropriate references to shared conventions, and the design template gives concrete structure. The main weakness is moderate verbosity in the template section, though the 800-word budget rule helps constrain output.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some redundancy — the design document format template is quite long and could be more compact. The mode-specific branching logic is repeated across steps. However, it mostly avoids explaining things Claude already knows. | 2 / 3 |
Actionability | The skill provides concrete, specific guidance: exact file paths, a complete markdown template for the design document, specific artifact keys, a structured return format, and clear rules. The steps are executable and copy-paste ready. | 3 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced with explicit steps: load skills → read codebase → write design → persist artifact → return summary. Step 4 is marked as MANDATORY. Mode-specific branching is clearly documented at each step. The persistence step serves as a validation checkpoint. | 3 / 3 |
Progressive Disclosure | The skill appropriately delegates shared concerns to `skills/_shared/sdd-phase-common.md` (Sections A-D) and `skills/_shared/openspec-convention.md`, keeping the main file focused on design-specific content. References are one level deep and clearly signaled. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- Gentleman-Programming/agent-teams-lite
- Commit
6901875
- 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.