Content
75%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 well-crafted, information-dense skill body: the delegation model (run the bundled script, relay output, guard the one risky confirmation) is unambiguous, safety constraints are explicit, and everything is project-specific knowledge rather than padding. The only deductions are minor: duplicated --dry-run/force-push statements, no literal example invocation, and PR-body construction details that could live in a reference file.
Suggestions
Consolidate the --dry-run explanation into one place — the Usage bullet and the closing paragraph of 'How to run' restate the same behavior (prints body, modifies nothing); a single statement would save tokens without losing the safety point.
Add one concrete example invocation, e.g. `python3 .claude/skills/bump-ark/bump_ark.py 1234 @:dailies`, next to the generic command so the common case is copy-paste ready.
Consider moving the PR-body construction mechanics (Closes collection, stack matching, release-notes scraping, squash-collapse rules) into a short reference file, keeping SKILL.md as the run/relay/confirm protocol overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific facts Claude cannot know (branch conventions, author-guard, exit code 3) and contains no padding about general concepts. However, the --dry-run behavior is explained twice (the Usage bullet "prints the assembled PR body to stdout and exits, touching no branch, ref, or PR" and again the closing paragraph "stdout is the PR body instead of a URL, and nothing is created or modified") and "never a force-push" is stated twice — minor instances of over-explanation that could be trimmed, matching the level-4 anchor rather than level 5 (every token earning its place) or level 3 (noticeably padded). | 4 / 5 |
Actionability | The core guidance is concrete and executable: "python3 .claude/skills/bump-ark/bump_ark.py <args>" with prerequisites ("It needs python3 and an authenticated gh") and fully specified argument forms ("/bump-ark <pr-number | main> [@:tag ...] [--confirm] [--dry-run]"). It stays at level 4 rather than 5 because no fully concrete example invocation (e.g., with a real PR number and tag) is shown — the common cases are covered by format spec rather than by a copy-paste-ready example with literal arguments. | 4 / 5 |
Workflow Clarity | The sequence is clear — forward args verbatim to the script, relay the printed PR URL ("Relay that URL. If it reports that the submodule is already at the target, relay that as-is"), and handle the refusal case — with an explicit error-recovery feedback loop for the author-guarded case (script exits 3 → relay owner and URL → ask the user → only on explicit confirmation re-run with --confirm). This is a non-destructive, safety-guarded workflow, so the destructive/batch cap does not apply. It sits at level 4 rather than 5 only because guidance for other failure modes (e.g., gh auth or API errors) and an explicit verification step after the PR is opened are absent. | 4 / 5 |
Progressive Disclosure | The single file is well organized (intro, Usage, How to run) and appropriately delegates implementation to the bundled script rather than inlining it, with vendored helpers clearly signaled ("parse_description.py is a vendored copy of posit-dev/positron-release-notes's parser"). No bundle files are present in this package to verify the referenced scripts, and the PR-body construction mechanics (stack matching, squash-collapse rules) run ~18 lines inline — good structure with minor organization gaps, matching level 4 rather than level 5's clean overview-plus-external-detail split. | 4 / 5 |
Total | 16 / 20 Passed |