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, 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 |