Content
70%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 instruction-dense, highly actionable skill body with exemplary workflow sequencing and validation gates, but it pays for that with significant verbosity — metaphor framing, duplicated protocol summaries, and repeated pipeline tables — and keeps clearly separable material (handoff template, hook setup, interop details) inlined in a ~420-line file instead of reference files.
Suggestions
Cut the 'Mental Model' wave-metaphor section, the 'No wipeouts. No zombie sessions.' taglines, and the 'Riding the Wave' re-summary of the pre-commit check (it duplicates 'The Monitoring Paradox' verbatim-protocol content) — this alone removes roughly a quarter of the body's tokens without losing any actionable guidance.
Move the handoff file template, 'Hook Integration' setup, and 'Interoperability with Other Skills' into reference files (e.g. references/handoff-template.md, references/hooks.md), keeping SKILL.md a lean overview with one-level-deep, clearly signaled references.
Compress or remove the 'Handoffs become learning signals' digression — it describes downstream tooling behavior rather than instructing the executing agent, and its bullet points ('Which drift signals most commonly trigger handoffs → …') add no action for the current session.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Noticeably verbose across several padded sections: the 'Mental Model' ocean-wave metaphor ('Paddling in', 'The shoulder', 'The close-out', 'Wipe-out territory'), tagline prose ('No wipeouts. No zombie sessions.'), the pre-commit anchor check explained in full under 'The Monitoring Paradox' and then re-summarized in 'Riding the Wave', and the pipeline/task-type table duplicated in both 'When to Use the Full Pipeline' and 'Pipeline position'. The 'Handoffs become learning signals' digression adds further padding. Not 'mostly efficient' (anchor 3) — roughly a third of the file could be cut without losing actionable content. | 2 / 5 |
Actionability | Fully executable throughout: copy-paste install commands ('gh skill install pskoett/pskoett-skills context-surfing'), 'entire status 2>/dev/null' detection, a complete handoff file template with named sections, hook JSON for .claude/settings.json with concrete path variants, Codex hook config, the fallback 'ls .context-surfing/handoff-*.md' command, the 'touch <handoff-path>.consumed' marker, and a scripted escalation message. Even the judgment-based drift signals are given as concrete, checkable examples ('it depends', 'could be', 'might want to consider'). | 5 / 5 |
Workflow Clarity | Every multi-step process is explicitly sequenced with validation checkpoints and feedback loops: Activation (numbered anchor-loading list), Recovery Protocol (Steps 1–2 with branch outcomes, 'at most one local re-anchor and one cold-context check' limits), Exit Protocol (Steps 1–3), next-session procedure (numbered 1–6), and Session Close. The pre-commit anchor check ('quote verbatim → state pending action → verify trace-back → on failure enter Recovery Protocol') is an explicit validation gate before side-effecting actions, and the cold-context subagent escalation path is a genuine error-recovery loop. | 5 / 5 |
Progressive Disclosure | In-file structure is good — clear section headers, and the one bundle reference (scripts/handoff-checker.sh) is real, correctly pathed, and clearly signaled. But ~420 lines are monolithic: the handoff file template, Hook Integration setup, and Interoperability sections are clearly separable reference-file material, and no references/ directory is used at all. Anchor 3 ('content that should be separate is inline') fits better than anchor 4 given the length and the multiple separable chunks. | 3 / 5 |
Total | 15 / 20 Passed |