Content
67%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 dense, command-rich operational guide: every mode has concrete commands, a dedicated Check validation gate, refuse-and-fix feedback loops, and a real, well-signaled reference file holding the file shapes. Its weaknesses are run-on sentences that stack many rules per step, and heavy reliance on external rules and sibling skills ("the block's Plan pages rule", pstack:bro, Lesson mode) that leave the guidance not fully self-contained.
Suggestions
Split multi-rule sentences into separate steps or a short list — Render step 8 and the PR-comment steps each bury 5+ distinct rules (publish routing, --new, pinning, reading rules) in one paragraph; pulling them apart would raise conciseness without losing content.
Define or inline the minimum needed from external dependencies ("the block's Plan pages rule", "the block's Plans and trails rule", pstack:bro) at first use, or move them to references/shape.md, so the commands are executable without knowledge the file never states.
Move the detailed PR-comment and publish-routing subsections into a second reference file (e.g. references/publishing.md) and keep one-line summaries in the mode table, so SKILL.md reads as the overview the mode table promises.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | There is no padding or explanation of concepts Claude already knows, but single sentences carry many rules at once — e.g. Render step 8 packs publish routing, checkout fork rules, the `--new` flow, Defaults rows, page-reading rules, pinning and Codex behavior into one paragraph. Mostly efficient but could be materially tightened, fitting the 3 anchor better than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Quotes: "node .agents/pstack/plan-page.mjs <plan> --check", "gh pr view <number> --json body --jq .body > <run directory>/body.md", "gh pr edit <number> --body-file <file>", "--attach", "--public", "--into" — concrete, copy-paste-ready commands with placeholders and a YAML example. Not 5 because execution repeatedly depends on context the file does not define ("the block's Plan pages rule", "pstack:bro", "sync-pstack's Lesson mode"), leaving gaps for a reader outside that ecosystem. | 4 / 5 |
Workflow Clarity | Quotes: "Walk [Check](#check)'s reading list before the first publish and after each revision", "It refuses every shape it can check and names the fix. Fix the plan or the subject file, never the HTML", plus a numbered Repair workflow — explicit validation checkpoints and a refuse-then-fix feedback loop are present. Not 5 because sequencing is blurred by cross-references ("Render steps 5, 7 and 8", "Render steps 3 to 6") and delegation to external rules ("as the Plan pages rule says"), so several checkpoints are implicit rather than self-contained. | 4 / 5 |
Progressive Disclosure | The body is an overview with a mode table, and the single reference is well-signaled and one level deep: "Read [references/shape.md](references/shape.md) before writing a plan or a subject file. It holds every file shape, the page order and the renderer's refusals" — and shape.md exists with exactly those sections. Not 5 because substantial detail (publish routing in step 8, the PR-comment subsection) stays inline where a further reference split would ease navigation, a minor organization gap per the 4 anchor. | 4 / 5 |
Total | 15 / 20 Passed |