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 strong, disciplined instruction-only skill: it states environment-specific rules with concrete commands, pre-action checkpoints, and if-then recovery paths for risky operations, without explaining concepts Claude already knows. The main room for improvement is trimming anecdotal justification and closing the few spots where guidance defers to another skill or stops short of a command.
Suggestions
Trim the war-story anecdotes (the overwriting incident quote and the false-revert investigation story) to one-line justifications — the rules they motivate are already clear without the narrative.
Inline the one or two essential commands deferred to other skills (e.g., the fetch command for completing shallow history, the minimal `new-branch` invocation) so the common cases are self-contained.
Consider moving "Reading a Codex peer's intent" (the Codex transcript-format walkthrough) into a reference file, keeping only the trigger conditions and the `ls` command in SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence (no git basics explained) and stays tight, but justifying anecdotes ("An agent once announced a revert from stat counts alone and was wrong; it cost a full investigation to disprove"; "Relaying between agents by hand is the user's most tedious job") and repeated "preserve and carry" phrasing are minor trim candidates. Not 5 because a few tokens are spent on narrative justification rather than instruction; not 3 because nothing is noticeably padded or over-explained. | 4 / 5 |
Actionability | Mostly executable guidance with concrete commands ("git log --oneline <base>..HEAD", "git status --short --untracked-files=all", "git worktree list --porcelain", "gh pr list --head \"$(git branch --show-current)\" --state open") covering the common cases. Minor gaps: "fetch complete history" and "follow `new-branch`" defer to elsewhere without giving the command or essential steps inline, keeping it below the copy-paste-complete level 5. | 4 / 5 |
Workflow Clarity | Each scenario has a clear sequence with pre-action checks and explicit if-then recovery ("If any path is unrelated or incomplete, keep the checkout in place and report the exact paths"; "If the work you were about to do just landed, continue from the latest branch snapshot"), and the revert-diagnosis section gives a decision rule (revert vs refactor hunks), so the destructive-operation validation cap does not apply. Not 5 because a couple of sections (Codex transcript reading, worktree carrying) lack explicit verification or error-recovery steps. | 4 / 5 |
Progressive Disclosure | Good structure: clear section headers, each scenario self-contained, and clearly signaled one-level references to sibling skills in the Related section ("`new-branch` — safe branch creation...", "`ship` — the commit/push/PR workflow..."). Not 5 because the body is ~110 lines with at least one section ("Reading a Codex peer's intent") that is a distinct sub-procedure which could live in a reference file, so the under-50-line exception does not apply; not 3 because organization and signaling are genuinely good with no inline content that obviously belongs elsewhere. | 4 / 5 |
Total | 16 / 20 Passed |