GitHub - ostikwhy-blip/claude-code-handoff-skill: A Claude Code skill that writes a verified HANDOFF.md so a fresh session can resume long-running work without repeating dead ends. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
ostikwhy-blip
claude-code-handoff-skill
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
master
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>3 Commits<br>3 Commits
assets
assets
LICENSE
LICENSE
README.md
README.md
SKILL.md
SKILL.md
View all files
Repository files navigation
handoff
A clean bridge between Claude Code sessions.
Long Claude Code sessions rot: context fills up, the model starts forgetting decisions, re-trying approaches that already failed, and describing files that no longer look like that. Starting a fresh session fixes the rot — but throws away everything the old session learned.
handoff writes a verified HANDOFF.md at your project root so the next session picks up exactly where this one left off, without repeating your dead ends.
A messy 3-hour session → /handoff → one clean file the next session resumes from.
Install
git clone https://github.com/ostikwhy-blip/claude-code-handoff-skill.git<br>cp -r claude-code-handoff-skill ~/.claude/skills/handoff
Start a new Claude Code session — done. No dependencies, no external APIs, no configuration.
Install for a single project instead<br>cp -r claude-code-handoff-skill your-project/.claude/skills/handoff
Use
End of a session (or when it starts feeling off):
/handoff
Claude verifies the actual state of your repo, then writes HANDOFF.md.
Start of the next session:
resume from the handoff
Claude reads the file, re-checks it against the current repo, surfaces open questions, confirms the plan with you — then continues the work, already knowing what failed last time.
That's the whole workflow. Two commands.
Why not just ask Claude to "summarize the session"?
Because that summary is written from a degraded model's memory, at exactly the moment that memory is least reliable. You get confident fiction: tests that "pass" but were never re-run, file descriptions that are twenty edits stale, hallucinated progress.
handoff is built around one rule: nothing goes in the file from memory alone.
Before writing a single line, Claude:
Runs git status, git log, git diff to reconstruct what actually changed — not what it believes changed
Re-reads every file the handoff will mention (a file that isn't where memory says is a caught hallucination, and gets corrected)
Re-runs your tests — "tests pass" is only written from output produced during the handoff itself
Every claim in the resulting file is tagged:
Tag<br>Meaning
[V]<br>Verified against the repo during this handoff — trust it
[?]<br>Recalled from memory, not re-checked — treat as a lead
When the next session resumes, it re-verifies the [V] claims against the current repo and reports any drift explicitly. Verification on both ends of the bridge.
What goes in the file
HANDOFF.md is capped at ~250–400 lines — long enough to carry what matters, short enough that a fresh session can actually absorb it. It covers:
Current goal and verified state — the actual state, not the intended one
Decisions made and why — so they don't get relitigated
Failed approaches and exactly why they failed — the single most valuable section. This is the knowledge a fresh session cannot reconstruct on its own, and the reason this skill exists
Known traps discovered in the codebase this session
Ordered next steps , concrete enough to act on without re-exploring
Open questions only you can answer
Every entry has to pass one quality gate: would a stranger with only this line avoid the mistake we made? If not, it gets a file, a line number, and a reason — or it gets cut.
Old handoffs aren't deleted — they're archived to .handoffs/, and still-relevant dead ends are carried forward automatically.
How it compares
Not a background memory. Ambient memory tools work invisibly; you never see what gets passed along. HANDOFF.md is a plain...