Content
85%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.
An exceptionally actionable, well-gated workflow document — every command is copy-paste ready and every branch has an explicit error path and user decision point. Its weaknesses are repetition of the anti-stop warning and a total absence of progressive disclosure: ~290 lines inlined in a single file with material (the split flow above all) that belongs in one-level-deep reference files.
Suggestions
Move the split check and split flow (~100 lines) into a references/split.md loaded only when a split is requested, keeping SKILL.md an overview with a clearly signaled pointer.
Consider the same treatment for the design-document section and resume details, which are only needed on their respective paths.
Consolidate the three restatements of the 'do not stop after spec new' warning in the opening into one authoritative statement to trim token cost without losing the emphasis.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every sentence is CLI-specific operational instruction with no generic concept explanations, but there is noticeable repetition: the "do not stop after spec new" warning appears three times in the opening (the STOP block, "This is a loop", and "Concretely: do not stop after spec new"), and split-decline handling is stated twice ("On a decline, continue exactly as if no split had been offered" / "On a decline, nothing is written"). Between anchors 3 and 4, noticeably above the midpoint. | 4 / 5 |
Actionability | Fully executable throughout: exact commands with complete --data JSON payloads (spec new with sources/epic, epic write/epic split staged under .spektacular/tmp/ with scratch-file cleanup), per-error-code responses (uncommitted_changes, auto_commit_failed, epic_complete), and a concrete epic_split.json outline. Copy-paste ready. | 5 / 5 |
Workflow Clarity | The state-machine loop is explicit (read instruction → perform → goto → repeat until the CLI says finished) with validation gates at every decision point: version check first, resume check before naming, the uncommitted-changes gate routed to the user, epic-complete confirmation, subagent review of split results, and the atomic restore on partial split failure. Feedback loops for error recovery are present throughout. | 5 / 5 |
Progressive Disclosure | No bundle files exist, so the entire 290-line body is one monolithic SKILL.md: the ~100-line split check/flow, design-document handling, and resume logic are all inlined where they clearly belong in separate reference files. Section headers are clear and well-organized (above anchor 2's 'minimal structure'), matching anchor 3's 'content that should be separate is inline'. | 3 / 5 |
Total | 17 / 20 Passed |