Content
92%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 exemplary script-orchestration skill body: lean, concrete, with explicit dry-run validation and error handling for a destructive operation, and well-organized for its size. The only notable gap is that the bundled executable it drives is absent from the skill bundle, leaving the body to coordinate rather than implement the mechanics.
Suggestions
Bundle scripts/worktree-cleanup.sh (or summarize its behavior and flags in the body) so the skill's guidance is fully executable from the skill alone.
Clarify step 2's pause logic — specify exactly when to pause for operator confirmation versus proceeding (e.g., an explicit 'proceed only after the operator confirms the dry-run output' condition).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 42-line body is lean: every section (What this does, Hard rules, Procedure, What 'merged' means, Cross-references) earns its place, explains nothing Claude already knows, and cites ADRs by number without re-explaining them. No trimming opportunities identified. | 5 / 5 |
Actionability | Concrete, copy-paste-ready commands (`scripts/worktree-cleanup.sh --dry-run`), specific diary-edit instructions including the empty-case text, and precise merged-detection criteria with the exact `gh pr list --head <branch> --state merged` fallback. Not 5 because the core git mechanics are delegated to an external script not present in the skill bundle, so the body alone cannot execute the actual cleanup operation. | 4 / 5 |
Workflow Clarity | Clear four-step sequence with explicit validation for a destructive operation: dry-run first and show the operator, hard rules handling the dirty-root error case ('surface that to the operator'), and a report step covering main before/after, removed worktrees, and 'worktrees kept and why' as a feedback loop. The destructive-operation cap does not apply because validation checkpoints are explicit. | 5 / 5 |
Progressive Disclosure | Under 50 lines with well-organized sections and no external references needed; per the simple-skill exception this warrants a 5. The pointers that do exist (scripts/worktree-cleanup.sh, docs/diary.md header protocol, ADR cross-references) are clearly signaled and one level deep. | 5 / 5 |
Total | 19 / 20 Passed |