Content
76%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.
A highly actionable, well-sequenced operational skill with copy-paste bash for every branch, held back by validation gaps around destructive operations (unconditional backup deletion, unverified `git reset --hard`) and minor dead-code/redundancy. Structure is good for a single-file skill, though its length invites some splitting into references.
Suggestions
Verify `./setup` succeeds before deleting the backup in the vendored path — gate `rm -rf "$INSTALL_DIR.bak"` on the setup exit code, mirroring the restore-on-failure handling already present in the auto-upgrade and Step 4.5 paths.
Add a post-upgrade verification checkpoint (e.g., compare `$INSTALL_DIR/VERSION` to the expected new version) before declaring success and before `git reset --hard`-based paths discard state.
Remove the duplicated `elif [ -d ".agents/skills/gstack/.git" ]` branch in Step 2 (dead code that wastes tokens) and consider moving the snooze-backoff and standalone-usage detail into reference files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is operational throughout — every step is a runnable bash block with terse directive prose and no explanation of concepts Claude already knows. It falls short of a 5 because of a duplicated dead `elif [ -d ".agents/skills/gstack/.git" ]` branch in Step 2 and repeated navigational restatements like 'Use the install directory from Step 2's output below'. | 4 / 5 |
Actionability | Every step provides fully executable, copy-paste-ready bash (install detection, version save, git/vendored upgrade, snooze backoff, sync), and the branches cover the common cases including all four AskUserQuestion options and failure-restore paths. Not below 5: placeholders like {old}/{new} are explicitly explained, so nothing is left as vague direction or pseudocode. | 5 / 5 |
Workflow Clarity | Steps 1–7 are clearly sequenced and some failure-restore loops exist (auto-upgrade setup failure, Step 4.5 sync failure), but destructive operations lack validation in several paths: the vendored path runs `rm -rf "$INSTALL_DIR.bak"` unconditionally even if `./setup` failed, and the manual git path has no checkpoint after `git reset --hard origin/main`. The rubric's cap — destructive workflows with missing validation cannot score above 3 — applies, so this does not reach 4 despite the strong sequencing. | 3 / 5 |
Progressive Disclosure | No bundle files exist; the single body uses well-organized, clearly headed step sections with no nested references, and the inline upgrade flow is deliberately inline for preamble reuse. Not 5: at ~220 lines, content such as the snooze-backoff script and the standalone-usage section could be split into reference files. | 4 / 5 |
Total | 16 / 20 Passed |