sdd-spec

Write SDD delta specs with requirements and scenarios. Trigger: orchestrator launches spec work for a change.

Quality

56%

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-spec/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, highly actionable skill that provides clear step-by-step workflows with appropriate validation checkpoints and concrete templates. Its main weakness is moderate verbosity — the RFC 2119 reference table and some explanatory passages add tokens without proportional value. The progressive disclosure pattern is sound with references to shared files, though the skill itself is long enough that some content could be externalized.

Suggestions

Remove the RFC 2119 Keywords Quick Reference table — Claude already knows these keywords and their meanings.

Consider moving the full delta spec format template and the new spec format template into a referenced file to reduce the main skill's length.

Dimension	Reasoning	Score
Conciseness	The skill is fairly long but most content is structural templates and workflow-critical details. The RFC 2119 quick reference table at the end is unnecessary (Claude knows these), and some explanatory text could be tightened (e.g., the 'Why copy-full-then-edit?' block is somewhat verbose). Overall mostly efficient but not maximally lean.	2 / 3
Actionability	The skill provides concrete, executable guidance: exact file paths, directory structures, complete markdown templates for delta specs and full specs, specific format for scenarios (GIVEN/WHEN/THEN), and a clear return summary template. The MODIFIED requirements workflow is particularly well-specified with an exact step-by-step process.	3 / 3
Workflow Clarity	The 6-step workflow is clearly sequenced with explicit dependencies (load skills → identify domains → read existing → write deltas → persist → return summary). The MODIFIED requirements workflow includes a critical validation concern (copy-full-then-edit to prevent data loss at archive time), and the persistence step is explicitly marked as MANDATORY. Conditional branching by mode (engram/openspec/hybrid/none) is clearly structured.	3 / 3
Progressive Disclosure	The skill references shared files (sdd-phase-common.md Sections A-D, openspec-convention.md, config.yaml) which is good progressive disclosure, but since no bundle files are provided, we cannot verify these references resolve correctly. The main SKILL.md itself is quite long and some content (like the RFC 2119 table or the full spec template) could potentially be split out. The references are one-level deep and clearly signaled, which is positive.	2 / 3
	Total	10 / 12 Passed

Description

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 a specific artifact type (SDD delta specs) but relies on internal jargon and system-level triggers rather than natural user language. It lacks concrete action verbs beyond 'write' and doesn't provide enough detail about what the skill actually produces or when a user would need it in natural terms.

Suggestions

Replace the internal trigger ('orchestrator launches spec work') with natural user-facing trigger terms like 'Use when the user needs to document a software change, write design specifications, or define requirements for a feature delta.'

Add more specific concrete actions such as 'Generates structured delta specifications including functional requirements, acceptance scenarios, impact analysis, and traceability matrices.'

Include natural keywords users might say: 'design doc', 'spec', 'requirements document', 'change specification', 'software design document'.

Dimension	Reasoning	Score
Specificity	It names a specific domain ('SDD delta specs') and mentions 'requirements and scenarios' as components, but doesn't list multiple concrete actions beyond 'write'. It's somewhat specific but not comprehensive.	2 / 3
Completeness	It answers 'what' (write SDD delta specs with requirements and scenarios) and has a 'when' trigger, but the trigger is system-internal ('orchestrator launches spec work') rather than user-facing explicit guidance. The 'when' is not framed as natural user scenarios.	2 / 3
Trigger Term Quality	The trigger terms are highly technical and internal-facing ('orchestrator launches spec work', 'SDD delta specs'). Users would not naturally say these phrases; they might say 'write a spec', 'design document', 'requirements', or 'change specification' instead.	1 / 3
Distinctiveness Conflict Risk	The term 'SDD delta specs' is fairly niche and unlikely to conflict broadly, but the description is vague enough that it could overlap with other specification-writing or documentation skills. The orchestrator trigger adds some distinctiveness but only within a specific workflow context.	2 / 3
	Total	7 / 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.