Content
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable framework for codebase exploration with a clear output template and step sequence. Its main weaknesses are the heavy reliance on external shared files without summarizing their key points, the lack of concrete executable guidance (no tool calls or specific commands), and missing validation checkpoints in the workflow. The output format template is a strength, giving Claude a clear deliverable structure.
Suggestions
Add concrete tool usage examples (e.g., specific file search commands, grep patterns, or tool calls) in Step 3 instead of only listing abstract investigation categories.
Inline brief summaries of what Sections A-D from sdd-phase-common.md require, so the skill is more self-contained and Claude doesn't need to load multiple files to understand the workflow.
Add a validation checkpoint after Step 3 (e.g., 'Verify you've read at least N relevant files and can describe the current architecture before proceeding to analysis') to ensure sufficient investigation before committing to recommendations.
Consolidate the persistence/retrieval instructions — the engram/openspec/hybrid/none modes are explained twice (in 'What You Receive' context and 'Retrieving Context') and could be a single reference table.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some redundancy — the persistence/retrieval instructions repeat references to shared docs multiple times across sections, and some steps (like 'Understand the Request') explain things Claude can infer. The ASCII tree in Step 3 adds visual clarity but the overall content could be tightened. | 2 / 3 |
Actionability | The skill provides a structured output template and a comparison table format, which are concrete. However, the actual investigation steps are descriptive rather than executable — there are no specific commands, tool calls, or code examples. Much of the actionable detail is deferred to shared files (sdd-phase-common.md sections A-D) rather than being present in the skill itself. | 2 / 3 |
Workflow Clarity | Steps are clearly numbered and sequenced (1-6), and the persistence step is marked as mandatory. However, there are no explicit validation checkpoints — no step to verify that the codebase investigation was sufficient, no feedback loop if the analysis is incomplete, and no verification that the artifact was successfully persisted. | 2 / 3 |
Progressive Disclosure | The skill references shared files (sdd-phase-common.md, openspec-convention.md) for detailed conventions, which is good progressive disclosure. However, the references are scattered throughout multiple sections rather than consolidated, and it's unclear what Sections A-D contain without reading those files, making navigation harder. | 2 / 3 |
Total | 8 / 12 Passed |