sdd-onboard
Walk users through the SDD workflow on the real codebase. Trigger: orchestrator launches onboarding for the full SDD cycle.
31
26%
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-onboard/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.
This description is too vague and jargon-heavy to be effective. It fails to explain what 'SDD' stands for or what concrete actions the skill performs, and its trigger clause relies on internal system terminology rather than natural user language. The description would benefit significantly from listing specific capabilities and adding user-facing trigger terms.
Suggestions
Define the 'SDD' acronym and list specific concrete actions the skill performs (e.g., 'Guides users through Spec-Driven Development: creating contracts, generating stubs, running validation tests').
Replace the internal system trigger ('orchestrator launches onboarding') with natural user-facing trigger terms, e.g., 'Use when the user asks about SDD onboarding, wants to learn the development workflow, or needs help with their first SDD cycle'.
Add common keyword variations a user might say, such as 'spec-driven development', 'development workflow', 'onboarding', 'getting started with SDD'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description says 'Walk users through the SDD workflow' which is vague — it doesn't specify what concrete actions are performed (e.g., generating stubs, running tests, creating contracts). 'SDD workflow' is an undefined acronym with no elaboration of capabilities. | 1 / 3 |
Completeness | It has a weak 'what' (walk through SDD workflow) and a 'when' trigger clause ('orchestrator launches onboarding for the full SDD cycle'), but the 'what' is too vague to be useful and the 'when' is narrowly tied to an internal system event rather than user-facing triggers. | 2 / 3 |
Trigger Term Quality | The trigger terms are highly specialized jargon ('SDD workflow', 'orchestrator launches onboarding', 'full SDD cycle') that a user would almost never naturally say. There are no common, natural language keywords that would help Claude match this skill. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'SDD workflow' and 'orchestrator launches onboarding' provides some specificity that reduces conflict with generic skills, but without defining what SDD is, it could overlap with other onboarding or workflow skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill functions as a scripted walkthrough coordinator that delegates real work to 7+ unbundled external skills while padding the content with verbose narration templates. The phase sequence is logical but the skill suffers from being simultaneously too verbose (scripted dialogue, concept explanations) and too vague (actual implementation delegated to missing references). It would benefit significantly from trimming narration, bundling referenced skills, and adding concrete validation checkpoints between phases.
Suggestions
Cut the scripted narration blocks to 1-line summaries — Claude can generate contextually appropriate dialogue without verbatim scripts, saving ~40% of token budget.
Bundle or inline the key referenced skills (sdd-propose, sdd-spec, sdd-design format requirements at minimum) so the skill is self-contained enough to execute.
Add explicit validation checkpoints between phases (e.g., 'Verify proposal.md exists and contains required sections before proceeding to Phase 4') and specify recovery actions when sdd-verify reports FAILING verdicts.
Extract the Phase 10 summary template and the onboarding change criteria into a referenced file to reduce the monolithic structure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~180 lines. It includes extensive narration templates that Claude doesn't need spelled out verbatim, explains obvious concepts ('Each scenario is a potential test case'), and repeats the SDD cycle concept multiple times. The quoted narration blocks are particularly wasteful — Claude can generate contextually appropriate narration without scripted dialogue. | 1 / 3 |
Actionability | The skill provides a clear 10-phase sequence with specific criteria (e.g., the onboarding change criteria tree is useful), but relies heavily on references to other skills (sdd-explore, sdd-propose, sdd-spec, etc.) without providing their content or concrete implementation details. The actual 'how' is delegated to external skills that aren't bundled, making this more of a coordination script than executable guidance. | 2 / 3 |
Workflow Clarity | The 10-phase sequence is clearly ordered and includes a checkpoint at Phase 3 ('ask before continuing past proposal'). However, validation/error handling is weak — the 'if anything blocks, STOP and explain' rule is vague, there are no explicit verification steps between phases, and the verify phase itself just says 'run sdd-verify behavior' without specifying what to do if verification fails beyond the archive step. | 2 / 3 |
Progressive Disclosure | The skill references 7+ external skills (sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive) and a shared file (sdd-phase-common.md) but none are bundled. The entire content is monolithic — all 10 phases are inline with verbose narration templates that could be separated. There's no clear navigation structure for the referenced materials. | 1 / 3 |
Total | 6 / 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.