agentleFS
upex-galaxyupex-galaxy/agentic-qa-boilerplate/.agents/skills/session-handoff/SKILL.md

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

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.
  • SethGammonSkill

    ascii-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

  • SethGammonSkill

    research-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-aiSkill

    live-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-aiSkill

    doc-gen

    Also in 4 projects that use this

  • flyingobsidianSkill

    terminology

    Read a codebase, find terminology, create/update definitions into a markdown document.

    Also in 3 projects that use this

  • Dizzy-TenSkill

    bug-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

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
  1. Distinctive:

    Write one when any of these is true:

    line 35
  2. Distinctive:

    Do NOT write one when the remaining work fits comfortably in the window.

    line 42
  3. Very specific:

    Launch the successor: Follow .agents/skills/session-handoff/references/successor-launch.md.

    line 48
  4. Distinctive:

    Perishable beats priority: If a perishable item needs attention before the priority list, say so in the same line.

    line 67

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 similarActually isUse
hand a scoped task to another session and supervise itorchestration: Task, Dispatch, mailbox, the work comes back/orca-orchestration
hand work away and stop caringownership transfer of a TASK, one direction, no returnthe binary's own orca-cli guide
remember a decision for next monthdurable cross-session fact, project-scopedEngram (mem_save)
shrink the window and keep goingharness compaction, lossy, not addressable, not yours to shapenothing to do
hand the whole SESSION to its own successorthis skillhere

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

  1. Capture. Walk .agents/skills/session-handoff/references/capture-contract.md section by section. Every section is mandatory; a section with nothing in it is written as an explicit none line, never omitted. Omission is indistinguishable from forgetting, and the successor cannot tell which happened.
  2. Write. Fill .agents/skills/session-handoff/templates/handoff.md to <<PRIMARY_ROOT>>/.session/handoffs/<session-name>-handoff-NN.md. Naming contract below.
  3. 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 count NN from 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 by bun run worktree:audit --rescue before the worktree goes.
  • NN is zero-padded, two digits, starting at 01, 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 the session= value of the AGENT IDENTITY: line the prompt hook injects (the same label the commit trailers carry), with spaces and parentheses replaced by -. When it reads unknown, 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

  1. Label every claim measured, read or predicted. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Every path is absolute. The successor may start in a different directory.
  6. 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.
  7. 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.
  8. 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.
  9. No AI attribution anywhere, ever (Critical Rule #3). A handoff is a repo artifact in English, even when the conversation is not.
  10. Do not delete the predecessor's handoff. The lineage is the audit trail. Writing -handoff-02 never removes -handoff-01.
  11. 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

FileWhat it holds
.agents/skills/session-handoff/references/capture-contract.mdthe ten mandatory sections, what each one is for, and the failure mode that justifies it
.agents/skills/session-handoff/references/successor-launch.mdlaunching the successor with and without a runtime, per harness; why this is not orchestration
.agents/skills/session-handoff/references/auto-trigger.mdwhether any harness exposes context size to a hook, with citations and a verdict
.agents/skills/session-handoff/templates/handoff.mdthe 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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.