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.
The body is a dense, highly actionable CLI reference with excellent error-recovery feedback loops and explicit workflows; it never wastes tokens on background concepts. Its main weakness is structural: the entire command syntax, STML details, and error catalog live inline in one long file with no reference files to defer detail to, and some guidance is duplicated across sections.
Suggestions
Split the detailed command syntax blocks and the 'Common errors' catalog into a references/ file (e.g., references/commands.md and references/errors.md), keeping SKILL.md to the workflow, session selection, and a quick-start subset of commands.
Remove the duplicated --source/--session-path guidance (present in both 'Session selection' and 'Reload') and consolidate the 'Workflow' and 'Typical flow' sequences into one.
Trim reminders that restate defaults Claude already follows (e.g., 'Quote --summary and --rationale defensively in the shell').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every line carries tool-specific facts Claude cannot know (flag semantics, UTF-16 offset semantics, note visibility rules, error catalogs), and it assumes competence throughout — no padding explaining what diffs or CLIs are. Not 5: there is avoidable duplication — the `--source` guidance appears in both 'Session selection' and 'Reload', the workflow appears twice ('Workflow' and 'Typical flow'), and bullets like 'Quote `--summary` and `--rationale` defensively in the shell' state things Claude already does by default. | 4 / 5 |
Actionability | Every section gives copy-paste-ready commands with concrete arguments — 'hunk session navigate --repo . --file src/App.tsx --new-line 372', the printf-batched 'comment apply --stdin' example, and 'highlight add ... --start 6 --end 19' — covering the common cases for each command family. Not 4: examples span inspect, navigate, reload, comments, highlights, and error recovery with executable syntax throughout, leaving no significant gaps. | 5 / 5 |
Workflow Clarity | The numbered 'Workflow' and 'Guiding a review' sequences are explicit, and the 'Common errors' section provides genuine feedback loops (error string → diagnosis → corrective command), including validation of the batch before mutation ('validates the full batch before mutating the live session') and a confirmation gate for the destructive daemon restart ('ask before running `hunk daemon restart --yes`; never restart unprompted'). Not 4: checkpoints are explicit and recovery-oriented, not just implicit. | 5 / 5 |
Progressive Disclosure | No bundle files exist (no references/, scripts/, or assets/), so everything — full CLI syntax blocks, STML markup details, and a long error catalog — is inlined in one ~220-line SKILL.md, which matches the anchor example of '[200 lines of API reference] that could be in a separate file'. Not 2: sections are well-organized with clear headers, not a wall of text; not 4: the detailed command reference and common-errors material would serve better in a one-level-deep reference file, which is a real organization gap rather than a minor one. | 3 / 5 |
Total | 17 / 20 Passed |