sdd-init
Trigger: sdd init, iniciar sdd, openspec init. Initialize SDD context, testing capabilities, registry, and persistence.
56
66%
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-init/SKILL.mdQuality
Discovery
75%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 provides clear trigger terms and explicitly addresses both what the skill does and when to use it, giving it strong completeness and distinctiveness. However, the specificity of capabilities could be improved by explaining what 'SDD context', 'registry', and 'persistence' mean in practical terms, and the trigger terms are quite narrow and technical, potentially missing more natural user phrasings.
Suggestions
Expand the capability description with more concrete actions, e.g., 'Sets up the SDD project structure, configures test runners, creates a component registry file, and enables state persistence for iterative development.'
Add more natural language trigger variations beyond command-like phrases, e.g., 'Use when the user wants to start a new SDD project, set up specification-driven development, or initialize an OpenSpec workspace.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names some actions ('Initialize SDD context, testing capabilities, registry, and persistence') but these are domain-specific terms that don't clearly explain what concrete actions are performed. The terms 'context', 'registry', and 'persistence' are somewhat abstract without further elaboration. | 2 / 3 |
Completeness | It explicitly answers both 'what' (initialize SDD context, testing capabilities, registry, and persistence) and 'when' (via the 'Trigger:' clause listing specific trigger phrases). The trigger guidance is explicit even if the format differs from 'Use when...'. | 3 / 3 |
Trigger Term Quality | It includes explicit trigger phrases ('sdd init', 'iniciar sdd', 'openspec init') which are useful command-like triggers, but these are narrow and technical. A user might not naturally say these exact phrases; common variations or more natural language triggers are missing. | 2 / 3 |
Distinctiveness Conflict Risk | The description is highly specific to SDD/OpenSpec initialization with very distinct trigger terms ('sdd init', 'openspec init'). It is unlikely to conflict with other skills due to its narrow, well-defined niche. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is well-structured with good progressive disclosure and clear decision logic via the gates table. Its main weaknesses are the lack of executable examples or concrete commands in the execution steps, and the absence of validation checkpoints for write operations. The content assumes familiarity with the SDD ecosystem but could be more actionable with specific code snippets or command templates inline.
Suggestions
Add at least one concrete example of the output envelope structure (even abbreviated) so Claude knows the exact shape to produce, rather than deferring entirely to references.
Insert explicit validation checkpoints in the execution steps — e.g., after step 4 (verify persistence wrote successfully) and after step 5 (verify registry file exists and is well-formed).
Include a brief inline example of what a detection result looks like (e.g., a sample stack summary) to make step 1 more actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient with good use of tables and structured sections, but the orchestrator gate preamble and some explanatory text (e.g., 'You are the phase executor: do the work yourself') add tokens explaining things Claude can infer. The decision gates table is well-structured but some rows could be tighter. | 2 / 3 |
Actionability | The execution steps provide a clear sequence and the decision gates table gives concrete branching logic, but there are no executable code examples, no specific commands, and key details (like what the structured initialization envelope looks like or how to build the skill registry) are deferred to references that aren't provided in the bundle. | 2 / 3 |
Workflow Clarity | The 7 execution steps provide a clear sequence, and the decision gates table handles branching well. However, there are no explicit validation checkpoints or error recovery steps — notably, step 4 (initialize persistence) and step 6 (persist capabilities) involve write operations with no validation/rollback guidance. The 'if openspec/ already exists, ask before updating' rule is a partial safeguard but not integrated into the workflow steps. | 2 / 3 |
Progressive Disclosure | The skill provides a clear overview with well-signaled one-level-deep references to init-details.md, engram-convention.md, and openspec-convention.md. Content is appropriately split between the main skill (decision logic, workflow, output contract) and referenced files for detailed templates and conventions. | 3 / 3 |
Total | 9 / 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.