Content
77%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 well-engineered behavioral skill: the drift-detection protocols, recovery decision tree, handoff template, and hook integration are concrete, executable, and clearly sequenced with real validation gates. Its weaknesses are length and monolithic structure — metaphor/aphorism padding, pipeline information repeated three times, and reference-worthy material inlined rather than split into bundle files.
Suggestions
Cut ~30% of the body by removing the "Principles" aphorisms and the surf "Mental Model" section, and stating the pipeline position once (keep the lifecycle diagram or the numbered pipeline list, drop the duplicate) — the wave vocabulary can survive as terminology without the explanatory metaphor.
Move the 40-line handoff template to a bundle file (e.g., assets/handoff-template.md or references/handoff-format.md) and reference it one level deep from the Exit Protocol, keeping only the file-naming convention and .consumed marker rules inline.
Move the cross-skill interoperability detail (relationship with intent-framed-agent, precedence/cadence rules, full pipeline table) into references/interop.md, keeping a two-line summary in the body; this also lets "Riding the Wave" item 2 drop its duplicated restatement of the pre-commit check in favor of a pointer.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The operational core (drift signal lists, recovery protocol, handoff template, hook setup) is efficient and non-obvious, but padded sections remain: the surf "Mental Model", the "Principles" aphorisms ("No wipeouts. No zombie sessions."), pipeline position stated three times (lifecycle diagram, task-type table, numbered pipeline list), and the pre-commit anchor check fully described in both "The Monitoring Paradox" and "Riding the Wave". Not 2 because the padding is flavor and repetition rather than explanations of concepts Claude already knows, and the wave lexicon is load-bearing terminology used consistently throughout. | 3 / 5 |
Actionability | Fully executable throughout: exact commands ("gh skill install pskoett/pskoett-skills context-surfing", "entire status 2>/dev/null", "ls .context-surfing/handoff-*.md"), a complete copy-paste JSON hook config, a full handoff file template with named sections, concrete file conventions (".context-surfing/handoff-[slug]-[timestamp].md", the ".consumed" marker), bounded retry limits ("at most one local re-anchor and one cold-context check"), and explicit fallback chains for every optional dependency (Entire CLI, context-monitor subagent). Judgment-dependent tasks like drift detection get concrete signal lists and scripts rather than vague direction. | 5 / 5 |
Workflow Clarity | The multi-step process is clearly sequenced (activation with anchor loading → drift monitoring → weak-signal recovery protocol → strong-signal exit protocol → next-session resumption) with explicit validation checkpoints: the pre-commit anchor check gates every side-effecting action, the recovery protocol has decision branches (reconcile / cold-context check / escalate / exit), and "Mark the handoff consumed only after re-entry succeeds" closes the resumption feedback loop. The handoff template functions as a checklist for the most fragile step. | 5 / 5 |
Progressive Disclosure | The one bundle reference is handled well — scripts/handoff-checker.sh is a real file, clearly signaled with install-path guidance for both install methods and the plugin variant — and external artifacts (intent-framed-agent, plugin/agents/context-monitor.md) are referenced with explicit fallbacks. However, the body is a ~430-line monolith: the 40-line handoff template, the cross-skill interoperability sections, and the task-classification table are inlined content that could live in separate reference files, leaving SKILL.md as a leaner operational core. That fits anchor 3 ("content that should be separate is inline") better than anchor 4. | 3 / 5 |
Total | 16 / 20 Passed |