session-handoff
Skill26 starsChanged 10 days agoMITView on GitHub
Compact an entire agent session into a handoff document so a NEW session resumes exactly where this one stopped, as if the context window had been extended rather than reset. Use when the context window is getting high (default threshold ~500k tokens, beyond which the model degrades and starts inventing), when work must continue past the end of this session, or on any variant of: hagamos el handoff, pasa el contexto a otra sesion, continua esto en otra sesion, hand this session over, continue this in a fresh session, write a handoff, session handoff. Produces <<PRIMARY_ROOT>>/.session/handoffs/<session-name>-handoff-NN.md (the primary checkout, also from a worktree) and, when an orchestration runtime is reachable, launches the successor itself in the SAME worktree and the SAME harness. Do NOT use for: delegating a scoped task to a worker while you keep working (that is orca-orchestration), one-shot subagent dispatch, or persisting durable project facts across projects (that is Engram memory).
149 other projects use a version of this.
Adopted by
Most recently taken up by
- lx-wnk/skillstheir own version, first seen Nov 16, 2026
- ingvarch/skillstheir own version, first seen Nov 16, 2026
- RMATI-11861/Claude-Skillstheir own version, first seen Nov 16, 2026
- Ivan-propio/claude-skillstheir own version, first seen Nov 16, 2026
- Valehead/ccBartheir own version, first seen Nov 16, 2026
- mlschodkowski/skillstheir own version, first seen Nov 16, 2026
Used with
Projects with it also use ascii-diagram, research-fleet and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SethGammonSkillascii-diagram
Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
Also in 4 projects that use this
SethGammonSkillresearch-fleet
Parallel research using Fleet wave mechanics. Spawns multiple scout agents, each investigating a different angle of the same question. Findings are compressed between waves. Produces a unified research brief from multiple independent perspectives.
Also in 3 projects that use this
vicoa-aiSkilllive-preview
Start a local app in the current user project, expose it through a tunnel, and return preview details in structured Markdown. Use when the user asks for a preview URL, public URL, shareable localhost, mobile/web preview, or tunnel setup.
Also in 4 projects that use this
botlearn-aiSkilldoc-gen
Also in 4 projects that use this
flyingobsidianSkillterminology
Read a codebase, find terminology, create/update definitions into a markdown document.
Also in 3 projects that use this
Dizzy-TenSkillbug-diagnosis
Diagnose bugs and product issues without modifying code. Use when the user explicitly invokes $bug-diagnosis or asks for diagnosis, root-cause analysis, issue classification, or fix strategy for code bugs, failing tests, configuration/dependency problems, deployment issues, performance regressions, data anomalies, or frontend/user-experience problems described through screenshots, annotations, logs, errors, or natural-language reports. Prioritize analysis and recommendations only; do not edit files.
Also in 3 projects that use this
- +1 more from SethGammon
Other versions149 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 149
- rohitg00/pro-workflow★ 2.9ksame name
- SethGammon/Citadel★ 927same name
- wanshuiyin/HERO-Anti-OverDefense★ 805same name
- OneWave-AI/claude-skills★ 378same name
- ai-analyst-lab/ai-analyst★ 304same name
- entireio/skills★ 240same name
- Innei/SKILL★ 92same name
- yuzushi-dev/session-handoff★ 67same name
- Hive-Academy/ptah-extension★ 34same name
- Hive-Academy/PtahCode★ 34same name
139 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository30 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- acliSkill
- agentic-qa-coreSkill
- agentic-qa-onboardSkill
- bug-screenshot-annotationSkill
- business-api-contextSkill
- business-data-contextSkill
- business-domain-contextSkill
- business-e2e-contextSkill
- evidence-artifactSkill
- exploratory-testingSkill
- framework-developmentSkill
- git-flow-masterSkill
- infra-contextSkill
- iql-contextSkill
- jira-administrationSkill
- judgment-daySkill
- orca-orchestrationSkill
- project-contextSkill
- project-discoverySkill
- pr-review-leadSkill
- regression-testingSkill
- shift-left-testingSkill
- sprint-conductorSkill
- sprint-testingSkill
- test-automationSkill
- test-documentationSkill
- test-framework-adaptationSkill
- xray-cliSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 127 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Write one when any of these is true:
- Distinctive: line 42
Do NOT write one when the remaining work fits comfortably in the window.
- Very specific: line 48
Launch the successor: Follow .agents/skills/session-handoff/references/successor-launch.md.
- Distinctive: line 67
Perishable beats priority: If a perishable item needs attention before the priority list, say so in the same line.
“Common” is measured: kept by at least 6 in 10 of the 127 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Session Handoff
A handoff is context transplanted, not context summarized. The successor is not a reader being briefed on someone else's work; it IS this session, with a new window. Everything it needs to act must be on disk, addressable, and true when it reads.
The skill is small on purpose. The heavy artifact is the markdown it produces, and the whole contract lives in .agents/skills/session-handoff/references/capture-contract.md.
What this is not
| Looks similar | Actually is | Use |
| hand a scoped task to another session and supervise it | orchestration: Task, Dispatch, mailbox, the work comes back | /orca-orchestration |
| hand work away and stop caring | ownership transfer of a TASK, one direction, no return | the binary's own orca-cli guide |
| remember a decision for next month | durable cross-session fact, project-scoped | Engram (mem_save) |
| shrink the window and keep going | harness compaction, lossy, not addressable, not yours to shape | nothing to do |
| hand the whole SESSION to its own successor | this skill | here |
The distinction that matters: compaction keeps what a summarizer judged salient. A handoff keeps what the NEXT actor needs, which is a different set, and it is written by the only party that knows the difference.
When to write one
Manual is the primary trigger and that is by design. The human notices the window filling, says so, and the skill runs. No polling, no nagging, no token spent guessing.
Whether any harness can trigger this automatically is answered, with citations, in .agents/skills/session-handoff/references/auto-trigger.md. Read it before promising the owner an automatic mode.
Write one when any of these is true:
- the context window is past the owner's threshold (~500k tokens unless the owner names a different one; it is a per-owner judgement about where this model starts degrading, not project configuration, so it stays in the conversation and not in a yaml key)
<!-- volatile-ok: owner-stated judgement threshold, explicitly not config --> - the session is about to end with work still in flight
- the session is about to do something that will itself consume a large slice of the window (a big harvest, a long file read) and the remaining budget will not cover the work after it
- the owner asks
Do NOT write one when the remaining work fits comfortably in the window. A handoff costs a real slice of context to produce, and a successor launched too early pays the startup tax for nothing.
The three steps
- Capture. Walk
.agents/skills/session-handoff/references/capture-contract.mdsection by section. Every section is mandatory; a section with nothing in it is written as an explicitnoneline, never omitted. Omission is indistinguishable from forgetting, and the successor cannot tell which happened. - Write. Fill
.agents/skills/session-handoff/templates/handoff.mdto<<PRIMARY_ROOT>>/.session/handoffs/<session-name>-handoff-NN.md. Naming contract below. - Launch the successor. Follow
.agents/skills/session-handoff/references/successor-launch.md. With a runtime, this session launches it. Without one, this session prints the line and the human pastes it.
Naming and location contract
<<PRIMARY_ROOT>>/.session/handoffs/<predecessor-session-name>-handoff-NN.md.session/is gitignored, and a handoff is disposable by design: it describes one session's state, it is not a project record, and committing it would put a decaying snapshot under version control.- It lives in the PRIMARY checkout,
<<PRIMARY_ROOT>>(.agents/README.md§"Checkout roots"), even when the session runs in a linked worktree. A handoff written inside a worktree dies with the worktree, and two worktrees of one lineage would each countNNfrom their own empty directory. The successor still launches in the SAME worktree as the predecessor; only the file lives in the primary. A handoff written into a worktree's own.session/by mistake is rescued bybun run worktree:audit --rescuebefore the worktree goes. NNis zero-padded, two digits, starting at01, incrementing across the whole lineage. List<<PRIMARY_ROOT>>/.session/handoffs/before choosing; never assume, and never count from a worktree's own.session/.- The successor's session name is the handoff file's basename without the extension. That is the entire naming rule, and it makes the lineage readable from the file list alone:
<base>, then<base>-handoff-01, then<base>-handoff-01-handoff-02. Long names are the point; a lineage you cannot read is a lineage you cannot audit. <predecessor-session-name>is thesession=value of theAGENT IDENTITY:line the prompt hook injects (the same label the commit trailers carry), with spaces and parentheses replaced by-. When it readsunknown, ask the owner for a name rather than inventing one.- A durable fact that outlives the session does not belong in the handoff. It belongs in Engram, in the repo, or in the tracker. The handoff cites it.
Hard rules
- Label every claim
measured,readorpredicted. The predecessor's guesses about what the successor will find are useful and are also the first thing to go stale. A predicted branch stated as fact sends the successor down a path that no longer exists. Measured means: this session ran it and read the output. Read means: it came from a document and was believed. - Mark perishable state
PERISHABLE, with the wall-clock time it was measured. Running workers, open mailboxes, in-flight PRs and live runs decay between writing and reading. The successor's instruction for anything marked perishable is: re-verify before acting, not act then discover. - Perishable beats priority. If a perishable item needs attention before the priority list, say so in the same line. A successor that follows a stale priority order while a live worker waits has done exactly what the handoff was supposed to prevent.
- Ids are copied, never described. A run id, a dispatch id, a terminal handle, a session id, a PR number, a tracker key, a commit SHA: verbatim, in backticks, in a form that can be pasted. "the worker from earlier" is not an id.
- Every path is absolute. The successor may start in a different directory.
- Name what is NOT done and why. A handoff that reads as an unbroken success is a handoff that hid something, and the hidden thing is always what bites.
- Write the file before launching the successor. They are not separable, and the order is not reversible: a successor that starts first reads a file that does not exist yet.
- Harness parity. The successor runs on the same harness as the predecessor. A handoff shaped for one agent's conventions handed to another is a translation problem nobody asked for.
- No AI attribution anywhere, ever (Critical Rule #3). A handoff is a repo artifact in English, even when the conversation is not.
- Do not delete the predecessor's handoff. The lineage is the audit trail. Writing
-handoff-02never removes-handoff-01. - No secrets in the file. A handoff names the variable a credential lives under (
$STAGING_USER_PASSWORD), never its value; a session cookie, a token or the path of an.auth/**state file stays out (Critical Rule #1;AGENTS.md§3 SESSION MATERIAL IN A DISPATCH).
References
| File | What it holds |
.agents/skills/session-handoff/references/capture-contract.md | the ten mandatory sections, what each one is for, and the failure mode that justifies it |
.agents/skills/session-handoff/references/successor-launch.md | launching the successor with and without a runtime, per harness; why this is not orchestration |
.agents/skills/session-handoff/references/auto-trigger.md | whether any harness exposes context size to a hook, with citations and a verdict |
.agents/skills/session-handoff/templates/handoff.md | the skeleton to fill |
Related doctrine: .agents/skills/agentic-qa-core/references/session-footer-contract.md (what a session reports at close), .agents/skills/agentic-qa-core/references/briefing-template.md (the 7 components, which a handoff deliberately is NOT: a briefing scopes a task, a handoff transplants a session).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

