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.
Excellent actionability and workflow clarity — every step is executable with explicit validation checkpoints and recovery paths. The weaknesses are redundancy between the inline workflow, the Guardrails section, and the bundled checklist reference, which inflates token cost and blurs what belongs in SKILL.md versus the reference file.
Suggestions
Consolidate the release sequence: keep SKILL.md as a lean overview of the workflow shape and move the detailed step-by-step sequence into references/stave-release-checklist.md, or drop the reference and keep the detail inline — currently both carry the same sequence.
Deduplicate the Guardrails section against inline rules (e.g. 'Never push directly to main', worktree removal rules, commit-title reliance each appear twice); keep guardrails only for rules not already enforced in their step.
Where steps need emphasis (e.g. 'Never push directly to `main`'), bold the rule inline in its step instead of restating it in a separate 21-bullet list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with directive, executable steps and assumes Claude's competence — no git or changelog concepts are explained. However, the 21-bullet Guardrails section substantially restates rules already stated inline (e.g. 'Never push directly to `main`' appears in step 8 and again in Guardrails; worktree-removal and commit-title rules are likewise duplicated), so it could be tightened. Matches 'efficient; minor instances... that could be trimmed' rather than the every-token-earns-its-place of score 5. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready commands throughout: `git rev-parse --show-toplevel`, `git tag --list 'v*' --sort=-version:refname | head -5`, `bunx --bun conventional-changelog-cli -p conventionalcommits -i CHANGELOG.md -s`, `bun run typecheck`, `git stash push --include-untracked -m "worktree-pr:release-x.y.z:<timestamp>"`, `git worktree add -b release-x.y.z ../.worktrees/<repo>/release-x.y.z HEAD`, `gh pr create --base main`. Concrete outputs are specified too (commit message `chore: release x.y.z`, 3–7 bullet summary shape). | 5 / 5 |
Workflow Clarity | A clear 10-step sequence with explicit validation checkpoints and feedback loops: pre-flight state checks (step 2), 'Verify before commit' with failure handling (step 6), post-PR diff review (step 8), and cleanup with a documented retry-once recovery path for a known failure mode ('If cleanup fails only because the shell is still inside the target worktree... change back... and retry once'). This matches the score-5 anchor with error-recovery guidance, not just the checkpoints of score 4. | 5 / 5 |
Progressive Disclosure | The single reference `references/stave-release-checklist.md` exists in the bundle, is one level deep, and is clearly signaled at the top — but the body then inlines a full 127-line detailed sequence plus guardrails, which overlaps the reference's 'exact sequence' content (the checklist repeats the same release steps and repo facts). The body itself directs the reader to the checklist 'for the exact sequence and repair rules' and then duplicates it, which is the 'content that should be separate is inline / could be better organized' pattern of score 3 rather than the 'most content appropriately placed' of score 4. | 3 / 5 |
Total | 17 / 20 Passed |