Content
70%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.
The body is a strongly actionable, well-validated workflow: every phase has executable commands, expected outputs, and explicit stop/error paths, and the routing logic is unambiguous. Its weaknesses are redundancy (four example outputs plus summary/quick-reference/bottom-line sections repeating the same content) and the absence of any progressive disclosure — everything, including ~150 lines of auxiliary material, lives inline in one long file.
Suggestions
Collapse Examples 2-4 into one canonical restoration example (they repeat the Phase 5 template with only field values changed) and remove the 'Quick Reference' and 'The Bottom Line' sections, which restate 'When to Use' and the core principle — this would address the conciseness gap.
Move the example outputs, 'Integration with Other Skills', and 'Best Practices' into a references/ file (e.g. references/examples.md) linked one level deep from a short '## Examples' section, giving the SKILL.md a lean overview as progressive disclosure expects.
Resolve the two actionability gaps: specify how to locate scripts/octo-state.sh (e.g. via the same OCTO_ROOT resolution used for feature-contract.py) and give a concrete worked invocation of feature-contract.py resume instead of the '<feature directory or spec path, empty when omitted>' placeholder.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly concrete commands and tables with no over-explanation of concepts Claude already knows, but it is noticeably padded: four near-duplicate example outputs (~115 lines) repeat the Phase 5 summary template, and 'Quick Reference', 'The Bottom Line', and 'Best Practices' restate earlier sections. This sits between anchors 2 and 3 — the issue is duplication rather than over-explanation — so 'mostly efficient but could be tightened' is the best fit. | 3 / 5 |
Actionability | The skill gives copy-paste-ready bash ('octopus state-path', './scripts/octo-state.sh read_state', the grep/sed extraction commands) with expected output formats and display templates. It falls short of anchor 5 due to minor gaps: the feature-contract.py invocation embeds a '<feature directory or spec path, empty when omitted>' placeholder, and the location of './scripts/octo-state.sh' is assumed without resolution. | 4 / 5 |
Workflow Clarity | Phases 0-6 are explicitly sequenced with per-step validation checkpoints ('.octo/' existence check, handoff-file check, 'Stop here - do not proceed to Phase 2', 'exit 1' on unresolvable state) and error-recovery feedback loops (the failed-restoration path with next-step guidance, and a per-status routing table covering nine statuses). This matches anchor 5: clear sequence, explicit validation, and error recovery; the skill is read-only, so the destructive-operation cap does not apply. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are all absent), so the entire ~540-line skill is one inline file. Sections are well-organized and navigable, but content that clearly belongs in separate reference files is inlined — the four full example outputs, 'Integration with Other Skills', and 'Best Practices' total roughly 150 lines of auxiliary material. The under-50-line simple-skill exception does not apply, so this fits anchor 3 ('some structure... content that should be separate is inline') better than anchor 4. | 3 / 5 |
Total | 15 / 20 Passed |