Content
57%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 genuinely actionable skill with strong safety gates (test-first, typed destructive confirmation, guarded PR creation) undermined by structural defects: duplicated step numbering, contradictory option numbering between the presentation and execution sections, an unterminated shell quote, and triple-redundant safety tables. It works as a single-file monolith but is over the size where inlining everything is efficient.
Suggestions
Fix the sequence defects: renumber the duplicated steps (two 'Step 4' and two 'Step 5' headers) and reconcile the option numbering so 'Present Options' and 'Execute Choice' agree on whether Create PR is option 1 or 2 — the current mismatch makes a user's 'option 1' ambiguous between merge and PR.
Close the unterminated quote in the Step 2 orchestrate.sh invocation and make the changelog step executable (an actual prepend command or heredoc) instead of a bare comment.
Collapse 'Red Flags - Never Do', 'Common Mistakes', and 'The Bottom Line' into one table (they restate the same three rules), and move the Claude Octopus integration notes into a separate reference file to cut the body roughly by a third.
Ship or guard the external script dependencies (orchestrate.sh, safe-gh-comment.sh) — they are referenced with absolute home paths but not present in the bundle, so execution fails on machines without the octopus plugin installed.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is command-first with essentially no explanation of concepts Claude already knows, but the same safety rules are restated three times ("Red Flags - Never Do", "Common Mistakes", "The Bottom Line"), and the "Integration with Claude Octopus" and "Quick Reference" table largely duplicate earlier content. That matches 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Most steps give concrete, executable bash (test-suite detection, merge sequence, push + guarded PR creation with a typed-confirmation discard flow). It stops short of 5 because Step 2's orchestrate.sh block has an unterminated quote (the embedded diff string never closes), Step 4's changelog step is only a comment ("Prepend to CHANGELOG.md if it exists"), and the octopus integration section is illustrative pseudo-flow rather than runnable code. | 4 / 5 |
Workflow Clarity | The pipeline has strong validation checkpoints (tests must pass before proceeding, typed "discard" confirmation, re-test after merge, error-recovery guidance in the PR block), but the sequence is broken by structural errors: the step numbers repeat (two "Step 4" and two "Step 5" headers after Step 5), and "Step 5: Present Options" numbers Create PR as option 1 while "Execute Choice" and the Quick Reference table number Merge Locally as option 1 — so 'user chose option 1' is ambiguous between merge and PR in a workflow that includes destructive actions. This lands at 'steps listed but with gaps/implicit mapping' rather than 4, where the sequence would be reliably followable. | 3 / 5 |
Progressive Disclosure | The skill is a single ~380-line file with no bundle (references/, scripts/, assets/ are absent), yet it references external scripts (${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh, safe-gh-comment.sh) that are not shipped in the bundle. Sections are well-labeled, but content that would naturally split out (the octopus integration notes, the option-by-option execution detail) is inlined in one monolithic file, matching 'some structure but could be better organized' rather than 4. | 3 / 5 |
Total | 13 / 20 Passed |