# Agent Skill Bundle — Session Handoff > Generated from the canonical public Skill source. This bundle is an invocation artifact, not a separate editable source. ## Agent instruction Apply this Skill to the user’s actual task. Follow its inputs, behavior, guardrails, outputs, and verification criteria. Do not merely explain or summarize the Skill. If required task context is missing, ask only for the missing information that blocks correct execution. ## Skill identity - source: skills/session-handoff - canonical human page: https://personal-ai-ops.vercel.app/wbeen/skills/session-handoff/ - version: 0.2.0 - workflow phase: execute - invocation: either ## Skill contract Preserve unfinished AI-assisted work before quota, context, runtime, or session limits interrupt it, then transfer and return execution safely across sessions, tools, or seats. ### Inputs - Current objective, acceptance criteria, and scope boundaries - Actual repository, branch, HEAD, worktree, and dirty-state evidence when code is involved - Completed, in-progress, remaining, blocked, and deferred work - Confirmed decisions, rejected approaches, and do-not-repeat constraints - Validation results, related issues or documents, and safe tool or skill metadata ### Outputs - A compact human-readable handoff brief - A machine-readable handoff capsule when filesystem or artifact support exists - A recoverable source checkpoint available to the receiving agent - One explicit next action and one authoritative execution-lease owner - A return handoff when an emergency executor temporarily took over ### Guardrails - Never invent usage percentages, model or tool versions, commits, pushes, test results, or runtime capabilities that were not actually observed. - Preserve task-relevant work; do not reset, clean, discard, or rewrite unrelated user changes while draining a session. - Keep credentials, tokens, authentication material, raw provider or MCP configuration, secret-bearing environment values, and secret-bearing logs out of the handoff package. - Treat operational checkpoint pushes as continuity operations, not approval to merge, force-push, release, deploy, change credentials, or perform destructive work. - Keep exactly one execution-lease owner for a handoff cycle; once the source is frozen, it must not keep modifying the same task independently. - The receiving agent must verify the actual repository and applicable instructions before accepting the lease. ### Verification - Every task-relevant source change is recoverable by the receiver before a ready signal is reported. - The successor can distinguish completed, in-progress, remaining, blocked, and deferred work without a full transcript. - Decisions, rejected approaches, validation evidence, repository identity, and one exact next action are explicit. - The receiver verifies real source state before continuing and the original owner can verify returned work without redoing completed implementation. ### Source instructions ## What it does Session Handoff is an **evacuation and return protocol for unfinished AI-assisted work**. It is used when the current execution window itself is becoming risky: quota, context, runtime, provider limits, or a deliberate switch between machines or agents. The goal is **recoverability, not transcript preservation**. The next agent should receive enough verified state to continue from the actual source, not enough prose to reconstruct an entire conversation. ## Two pressure stages ### PREPARE — 80% default when credible telemetry exists PREPARE is cheap and reversible. - Keep working. - Refresh the compact objective, decisions, repository identity, validation evidence, and likely next action. - Refresh a local handoff package when useful. - Avoid opening a large new branch of work that cannot be drained safely. - Do not create an extra remote checkpoint merely because PREPARE was entered. The 80% threshold is a default for environments that expose trustworthy quota or rate-limit telemetry. If the host does not expose it, do not manufacture a percentage. Use a provider warning, explicit operator request, or an `unknown` / `manual` signal instead. ### EVACUATE — 90% default or equivalent near-limit signal At EVACUATE, enter drain mode: 1. Do not begin a new large implementation step. 2. Finish only the smallest safe atomic operation already underway. 3. Inspect the actual repository, worktree, branch, HEAD, staged/unstaged state, and applicable instructions. 4. Run only the minimum useful validation likely to finish safely. 5. Preserve every task-relevant source change. 6. Make the source state recoverable by the receiver. 7. Produce the handoff package. 8. Transfer the execution lease and freeze the source side. 9. Report a ready signal only when the receiver can actually recover the work. A provider near-limit warning, insufficient remaining capacity, or a manual `HANDOFF NOW` request can enter EVACUATE directly. ## Portable handoff package A practical filesystem shape is: ```text .session-handoff/ └─ / ├─ manifest.json └─ HANDOFF.md ``` The machine-readable capsule should capture only continuation-critical state: - trigger reason and only actually observed usage data; - source and destination role when relevant; - cycle ID and transfer leg; - objective, acceptance criteria, scope, and out-of-scope boundaries; - repository/worktree/base/current branch, HEAD, upstream, dirty state, and relevant files; - completed / in-progress / remaining / blocked / deferred work; - decisions, assumptions, rejected approaches, and `do_not_repeat` items; - validations actually run, including failures and not-run checks; - safe metadata for skills, tools, integrations, and instructions actually used; - recoverable checkpoint location; - first files to read, one exact next action, risks, and decisions not to change silently. The human brief is the scan-first view of the same state. It should not become a transcript dump. ## Source recoverability comes first A context document alone is not a handoff when source changed. Prefer the least expensive repository-approved mechanism that makes the exact work available to the receiver: 1. the existing task branch/current remote branch checkpoint; 2. a repository-specific handoff branch or orchestrator checkpoint; 3. an approved shared filesystem or worktree; 4. capsule-only only when source did not change. An operational checkpoint push does **not** imply permission to push protected main, merge a PR, force-push, tag/release, deploy to Production, change credentials, or perform destructive operations. ## Execution lease A handoff cycle has one authoritative executor. - Before transfer, the current owner holds the lease. - After `HANDOFF_READY`, the destination accepts the lease only after verifying the real repository and instructions. - Once the source side is frozen, it can review or communicate but should not independently keep editing the same task. - If the work later returns, the same rule applies in reverse. This avoids split-brain work when the same task exists on two machines, sessions, or agents. ## Verified takeover The receiver does not start implementing immediately after reading a handoff. 1. Read the capsule and human brief. 2. Fresh-read repository instructions such as `AGENTS.md` or `CLAUDE.md`. 3. Verify repository identity, branch, HEAD, working tree, and referenced files. 4. Compare the recorded checkpoint with actual source state. 5. Let real source state win when the capsule is stale. 6. Accept the execution lease only after verification. 7. Resume from the recorded single next action. 8. Do not repeat completed work or explicitly rejected approaches without new evidence. ## Optional emergency-return profile Some teams have a normal execution environment and a separate emergency environment with more available capacity. Session Handoff supports a bidirectional cycle: ```text PRIMARY / NORMAL → PREPARE → EVACUATE → HANDOFF_READY → EMERGENCY TAKEOVER + WORK → RETURN_HANDOFF_READY → PRIMARY VERIFY + RESUME/REVIEW → CLOSED ``` The labels can represent different seats, machines, accounts, people, or providers. The protocol is the same: make source recoverable, transfer one lease, and return it explicitly. A return handoff is required even when the emergency executor finished all implementation. The original owner should resume at **review/verification**, not redo completed work. ## Manual fallback is part of the design Provider-specific status lines, hooks, or quota adapters can improve trigger quality, but they are optional. A host-neutral protocol should still work when automation is unavailable: - telemetry adapter available → trigger PREPARE/EVACUATE automatically at a safe boundary; - only provider warning available → use that warning; - no reliable signal available → manual prepare/handoff remains the fallback. Automation must never fabricate a threshold event from token or context estimates. ## How this differs from Agent Handoff **Agent Handoff** is the general skill for planned transfers between agents or sessions. **Session Handoff** is the continuity specialization for execution-window risk. It adds: - pressure-aware PREPARE and EVACUATE stages; - recoverable source checkpoints; - one-owner execution leases and source freezing; - verified takeover; - explicit return handoff and closure; - optional provider adapters without making the core protocol provider-specific. Use Agent Handoff for a calm planned transfer. Use Session Handoff when interruption risk itself must be managed. ## Completion rule Return the useful task result first. Then state briefly which verification criteria passed, which could not be checked, and any stop/escalation condition that remains.