Claude Code skill · oh-my-pi inspired
Hand off the work, not the context loss.
When a session runs long, handoff compacts everything that matters into one structured markdown file — objective, what's done, what's left, the exact next action — so a fresh-context agent resumes with zero ambiguity.
What it does
01An artifact, not an intention.
Captures exact state, not vibes
Real file paths, commands, test results, error text. The read/modified file sets are derived mechanically from tool history, never from recall.
Defends cold-resume failures
An explicit DO-NOT-REDO done list, a single exact next step, and any pending user question preserved verbatim.
Paste-ready & chainable
Writes handoffs/handoff-<timestamp>.md and emits a <handoff-context> block to paste into a fresh chat; each doc links to its predecessor.
How it works
02Gather → structure → write → verify.
Gather
Scan transcript + tool history, derive read/modified sets, run read-only git/test probes.
Structure
Fill the fixed template — Current State first, Done labeled DO NOT REDO.
Write
Save handoffs/handoff-<UTC>.md, fill the Handoff Chain link; merge a prior handoff if present.
Verify
Run the quality checklist: no secrets, no placeholders, copy-paste verify commands, open question preserved.
Default to a single reasoning pass with tools off — pure writing, no busywork.
Template sections
03Every part, always in the same place.
Current State (read this first)
One paragraph of what is true right now plus the active blocker; placed first to kill the "where was I" cost.
Metadata
Project path, git branch + HEAD, clean/dirty tree, agent/model — so staleness is detectable before any work.
Goal
The specific, measurable objective the user is trying to accomplish.
Constraints & Preferences
Constraints, requirements, and stated preferences the resuming agent must honor.
Progress
Three buckets — Done (DO NOT REDO, quantified, with evidence), In Progress, Pending (ranked by impact) — so finished work is never duplicated.
Immediate Next Step
The single exact first action to take, removing all ambiguity about where to start.
Key Decisions
Each decision paired with its rationale, so settled choices are not relitigated or silently reversed.
Files / Areas Touched
Files with purpose-of-change, plus mechanically-derived <read-files>/<modified-files> tags showing the real blast radius.
Key Patterns / Conventions
Non-obvious conventions discovered in this codebase, so the resuming agent matches existing style.
Gotchas / Landmines
Known traps and their workarounds, to prevent the resuming agent from re-hitting them.
Verification
Copy-pasteable build/test/lint commands plus the expected healthy result, to confirm state fast.
Open Questions (verbatim)
Any unanswered user/caller question, preserved word-for-word — the most resumption-critical, most-failed item.
Handoff Chain
A continues-from link to the predecessor handoff and this doc's own path, forming a durable audit trail.
Install
04Clone, symlink, done.
Invoke it explicitly with "create a handoff", or let it trigger on a milestone or after 5+ edits. Output lands in handoffs/ in your working project.
Example output
05See the artifact, not just the idea.
examples/ → full coding + debugging examples in the repo.