Content
63%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong operational skill: the workflow is explicitly sequenced with batch validation, conflict detection, user confirmation, and per-change failure isolation, and the core commands are copy-paste ready. Its weaknesses are redundancy (output templates and guardrails duplicate the step content) and zero progressive disclosure — the long worked examples and output templates should live in a reference file. The deferred 'openspec-sync-specs approach' and vague 'search the codebase' step are the main actionability gaps.
Suggestions
Move the 'Conflict Resolution Examples' and the three output-template sections into a references/ file (e.g. references/examples.md) and link to it, keeping SKILL.md as a lean ~150-line workflow.
Delete the Guardrails entries that restate inline step instructions, and collapse the three 'Output On ...' sections into one parameterized template since step 9 already shows a filled-in example.
Make the two vague steps concrete: specify how to search for implementation evidence (e.g. grep for requirement-named functions/tests) and inline a short summary of the sync procedure instead of just naming 'the openspec-sync-specs approach'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The nine steps are dense and earn their tokens, but there is real duplication: step 9's summary example is repeated nearly verbatim in the 'Output On Success'/'Output On Partial Success' sections, and the Guardrails restate inline instructions ("Always prompt for selection, never auto-select" duplicates step 2's "IMPORTANT: Do NOT auto-select"). Mostly efficient but could be tightened by ~80 lines, matching anchor 3 rather than 4. | 3 / 5 |
Actionability | Concrete and mostly executable: `openspec list --json`, `openspec status --change "<name>" --json`, the `mkdir -p`/`mv` archive commands, exact table and output formats. Minor gaps keep it below 5: "Search the codebase for implementation evidence" gives no concrete search method, and "Use the openspec-sync-specs approach (agent-driven intelligent merge)" defers to another skill without any inline detail. | 4 / 5 |
Workflow Clarity | A clearly sequenced 9-step workflow with explicit validation for a batch/destructive operation (step 3 batch validation, step 4 conflict detection, step 6 status table, step 7 user confirmation, step 8 per-change outcome tracking, and the guardrail "If archive target exists, fail that change but continue with others"), so the batch-operation cap at 3 does not apply. Not 5 because there is no post-archive verification or fix-and-retry feedback loop. | 4 / 5 |
Progressive Disclosure | The skill is a single file with no references/ directory, and the ~235-line body inlines auxiliary content that belongs in a reference file: the ~35-line 'Conflict Resolution Examples' section and the three separate output-template sections. Sections are well-organized and navigable, but content that should be separate is inline, matching anchor 3. | 3 / 5 |
Total | 14 / 20 Passed |