sdd-design

Create the SDD technical design and architecture approach. Trigger: orchestrator launches design for a change.

Quality

51%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./internal/assets/skills/sdd-design/SKILL.md

Quality

Content

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

Description

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

Validation

81%

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 — 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: 27 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.