sdd-archive
Archive a completed SDD change by syncing delta specs. Trigger: orchestrator launches archive after implementation and verification.
52
59%
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-archive/SKILL.mdQuality
Discovery
42%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 narrowly targeted at an internal orchestration workflow, which gives it strong distinctiveness but poor discoverability for human users. It relies heavily on domain-specific jargon without explaining the concrete operations involved, and the trigger mechanism is system-driven rather than user-driven, limiting its usefulness as a skill selection guide.
Suggestions
Replace or supplement jargon ('SDD', 'delta specs') with plain-language explanations of what the skill actually does, e.g., 'Moves completed design document changes to an archive by synchronizing specification deltas.'
Add natural trigger terms a user might say, such as 'archive design changes', 'finalize SDD', 'sync completed specs', even if the primary trigger is automated.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | It names a domain-specific action ('archive a completed SDD change by syncing delta specs') but only describes one action and uses jargon ('SDD', 'delta specs') without explaining what concrete operations are performed. | 2 / 3 |
Completeness | It answers 'what' (archive a completed SDD change by syncing delta specs) and has a 'when' clause ('orchestrator launches archive after implementation and verification'), but the trigger is system-internal rather than explicit user-facing guidance. The 'Trigger:' clause functions similarly to 'Use when' but is narrowly scoped to an automated orchestrator context. | 2 / 3 |
Trigger Term Quality | The trigger terms are highly technical and internal ('SDD change', 'delta specs', 'orchestrator launches archive'). No natural user-facing keywords are included; a user would never naturally say these phrases. | 1 / 3 |
Distinctiveness Conflict Risk | The description is highly specific to a niche workflow (SDD archival via delta spec syncing triggered by an orchestrator), making it very unlikely to conflict with other skills. | 3 / 3 |
Total | 8 / 12 Passed |
Implementation
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, actionable skill with clear step sequencing, explicit validation checkpoints, and concrete file paths and commands. Its main weakness is moderate verbosity from repeating mode-based branching (engram/openspec/hybrid/none) across every step rather than consolidating the decision logic. The progressive disclosure pattern is reasonable with references to shared files, though the absence of bundle files makes it impossible to verify those references.
Suggestions
Consolidate the mode-based branching into a single decision table at the top of the skill (e.g., a matrix of mode × step showing which steps apply), rather than repeating IF/SKIP blocks in every step.
Consider extracting the detailed merge algorithm (Step 2) into a referenced file to keep the main skill leaner as an overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some redundancy — the mode-based branching (engram/openspec/hybrid/none) is repeated across nearly every step, which could be consolidated into a single decision table. The orchestrator gate preamble and some explanatory text could be tightened. | 2 / 3 |
Actionability | The skill provides concrete, specific instructions: exact file paths, bash-style copy commands, a clear merge algorithm (ADDED/MODIFIED/REMOVED), a verification checklist, and a complete output template with markdown table format. Guidance is copy-paste ready and leaves little ambiguity. | 3 / 3 |
Workflow Clarity | Steps are clearly numbered and sequenced (load → sync → move → verify → persist → return). Explicit validation checkpoints exist in Step 4 with a checklist, and the rules section includes a destructive-merge warning gate. The feedback loop for dangerous merges (warn orchestrator, ask confirmation) is present. | 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 no bundle files are provided to verify these exist. The main file itself is fairly long and the mode-branching logic repeated in every step could potentially be extracted. References are one-level deep and clearly signaled, which is positive. | 2 / 3 |
Total | 10 / 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.