kanso-handoff
Packages what this session knows into .claude/handoff.md so /clear costs nothing. The file is a baton, not a log: each run overwrites the last, the next session reads it and continues, and nothing else is kept.
The audience is the next agent session, not a person. Density beats politeness; a fact the next session must not re-derive beats a paragraph about how it was derived. Everything in kanso-principles about earning lines applies double here, because every line of the handoff is paid for at the start of every future turn.
What goes in
Header first, one line: date, branch, HEAD short sha. The next session diffs against this to detect drift since the handoff.
Then these sections, each optional, each tight. $ARGUMENTS may narrow the pack to one strand of a mixed session.
| Section |
Holds |
Rule |
| Goal |
The task, one or two sentences, user's point of view |
Present tense, no history |
| State |
Done and verified / done but unverified / not started |
Verified means a command ran and passed, nothing softer |
| Decisions |
Each with its one-line reason |
A decision without the why gets re-litigated next session |
| Files |
Load-bearing paths, one line each |
Repo-relative; say what each is, not what happened to it |
| Open threads |
Numbered next steps, most important first |
Imperative, self-contained |
| Dead ends |
What was tried and abandoned, and why |
Saves the next session from retrying it |
| Verify |
Exact commands with expected outcomes |
Runnable as written |
What stays out
- Transcript narration. "We then discussed" is the failure mode; the next session was not there and does not care.
- Anything git already records. The diff is in git; the handoff carries what the diff cannot say.
- Secrets, always. No tokens, keys, or credentials, even when they appeared in the session. Name where a secret lives (
op://..., an env var) rather than what it is.
- Unfounded certainty. Anything not verified is written as unverified.
- Durable knowledge. Repo guidance belongs in AGENTS.md via
kanso-context; solved-problem notes belong to a memory tool. The handoff dies at the next overwrite.
The ceiling
150 lines, hard. Context research is unambiguous that long context files degrade the agents reading them. When over, cut in this order: Dead ends, Files detail, State detail. Never cut Decisions or Open threads; those two sections are the reason the file exists.
The run
- Distil the session into the format above. Resolve relative dates to absolute. Check the result against the ceiling.
mkdir -p .claude if needed; write .claude/handoff.md, replacing any previous handoff without ceremony.- If the repo tracks
.claude/ and handoff.md is not ignored, say so once and suggest the .gitignore line. Warn, do not block: a committed handoff is untidy, not dangerous.
- End with exactly this, and no report:
Handoff written to .claude/handoff.md (<n> lines). After /clear or in a new session, paste:
Read .claude/handoff.md and continue.
What this skill never does
- Append or archive. One file, overwritten. History is git's job.
- Write a secret into the file, whatever the session contained.
- Pad the pack toward the ceiling. A ten-line handoff for a ten-line session is correct.
- Touch AGENTS.md, CLAUDE.md, or any durable context file.
- Editorialise. The pack states; it does not persuade.
1---2name: kanso-handoff3description: Use when the user wants the current session's context packaged for the next one: "package this session", "carry this context over", "before I /clear", "handoff", "save where we are", "compact this into a prompt for next time". Writes one dense, machine-readable file and prints the resume line. Not for durable repo guidance (kanso-context) or permanent solution notes.4---56# kanso-handoff78Packages what this session knows into `.claude/handoff.md` so `/clear` costs nothing. The file is a baton, not a log: each run overwrites the last, the next session reads it and continues, and nothing else is kept.910The audience is the next agent session, not a person. Density beats politeness; a fact the next session must not re-derive beats a paragraph about how it was derived. Everything in `kanso-principles` about earning lines applies double here, because every line of the handoff is paid for at the start of every future turn.1112## What goes in1314Header first, one line: date, branch, `HEAD` short sha. The next session diffs against this to detect drift since the handoff.1516Then these sections, each optional, each tight. `$ARGUMENTS` may narrow the pack to one strand of a mixed session.1718| Section | Holds | Rule |19|---|---|---|20| Goal | The task, one or two sentences, user's point of view | Present tense, no history |21| State | Done and verified / done but unverified / not started | Verified means a command ran and passed, nothing softer |22| Decisions | Each with its one-line reason | A decision without the why gets re-litigated next session |23| Files | Load-bearing paths, one line each | Repo-relative; say what each is, not what happened to it |24| Open threads | Numbered next steps, most important first | Imperative, self-contained |25| Dead ends | What was tried and abandoned, and why | Saves the next session from retrying it |26| Verify | Exact commands with expected outcomes | Runnable as written |2728## What stays out2930- Transcript narration. "We then discussed" is the failure mode; the next session was not there and does not care.31- Anything git already records. The diff is in git; the handoff carries what the diff cannot say.32- **Secrets, always.** No tokens, keys, or credentials, even when they appeared in the session. Name where a secret lives (`op://...`, an env var) rather than what it is.33- Unfounded certainty. Anything not verified is written as unverified.34- Durable knowledge. Repo guidance belongs in AGENTS.md via `kanso-context`; solved-problem notes belong to a memory tool. The handoff dies at the next overwrite.3536## The ceiling3738150 lines, hard. Context research is unambiguous that long context files degrade the agents reading them. When over, cut in this order: Dead ends, Files detail, State detail. Never cut Decisions or Open threads; those two sections are the reason the file exists.3940## The run41421. Distil the session into the format above. Resolve relative dates to absolute. Check the result against the ceiling.432. `mkdir -p .claude` if needed; write `.claude/handoff.md`, replacing any previous handoff without ceremony.443. If the repo tracks `.claude/` and `handoff.md` is not ignored, say so once and suggest the `.gitignore` line. Warn, do not block: a committed handoff is untidy, not dangerous.454. End with exactly this, and no report:4647```48Handoff written to .claude/handoff.md (<n> lines). After /clear or in a new session, paste:4950Read .claude/handoff.md and continue.51```5253## What this skill never does5455- Append or archive. One file, overwritten. History is git's job.56- Write a secret into the file, whatever the session contained.57- Pad the pack toward the ceiling. A ten-line handoff for a ten-line session is correct.58- Touch AGENTS.md, CLAUDE.md, or any durable context file.59- Editorialise. The pack states; it does not persuade.
blakecyze