Content
88%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 ship workflow: every step has executable commands, explicit abort conditions, and feedback loops for error recovery, with heavy emphasis on repo-specific gotchas that Claude could not infer. The main improvement opportunities are trimming rationale that re-explains basic shell/git behavior and offloading the two large inline procedures (sync-fix rebuild, scrub patterns) to reference files.
Suggestions
Trim parentheticals that re-explain known shell/git semantics (e.g., 'a bare wait swallows child exit codes', 'plain git log is newest-first') — keep only the non-obvious repo-specific gotchas to push conciseness toward 5.
Move the step-2 sync-fix rebuild procedure and the 'What to Omit' scrub grep patterns into reference files (e.g., references/sync-fix.md, references/scrub.md), keeping a one-line trigger in SKILL.md, to reduce the always-loaded token cost.
Condense the long prose paragraph in step 6 warning against 'mship:generate' into a short bulleted do/don't list — the same information reads faster and is less likely to be skimmed past.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with zero padding — every step is operational ('A failing test aborts ship', 'Do not ship with any generator or audit failing'). However, several parentheticals explain shell/git semantics Claude already knows: 'a bare wait swallows child exit codes', 'plain git log is newest-first', 'git stash drop rejects a raw SHA'. These are minor over-explanations that could be trimmed, matching anchor 4. Not 3: the overwhelming majority of tokens carry repo-specific, non-obvious information (shared stash lists across worktrees, ENOENT-prone umbrella generator); not 5: some rationale paragraphs re-derive known git behavior. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: exact commands with exit-code gating ('bun run lint || { echo "❌ lint failed — do not ship"; exit 1; }'), the stash-pinning bash block, scrub grep regexes, the verbatim PR template, and the exact 'gh pr create --base staging' invocation. Not 4: there are no gaps — even failure paths specify exactly what to run and what aborts ship. | 5 / 5 |
Workflow Clarity | A 9-step sequence with explicit validation checkpoints and feedback loops at every risky point: re-verify 'git log --oneline origin/staging..HEAD' after rebase, 'abandon it and rebuild' on stray commits, 'fix the cause (never silence it) and re-run' after audit failures, and the final PR content check that loops back ('redo step 2's fix and git push --force-with-lease'). Destructive operations (history rewrite, force-push, branch deletion) all have validation, so the destructive-operation cap does not apply. Not 4: checkpoints are explicit, not merely present. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the body's cross-skill references ('/cleanup', '/test-audit', '/db-migrate') are clearly signaled and one level deep. The single file is well-sectioned (Your Task, Commit Message Format, What to Omit, PR Description Format, Important Notes) and navigable. Not 5: at ~186 lines, substantial standalone procedures — the step-2 sync-fix rebuild and the 'What to Omit' scrub patterns — are inlined rather than offloaded to reference files; not 3: organization is good, not merely present. | 4 / 5 |
Total | 18 / 20 Passed |