AI-assisted engineering does not usually fail because an agent forgets everything. It fails because a new session receives the wrong kind of context. Give it too little and it repeats discovery, reopens decisions, or changes the wrong files. Give it an entire transcript and it has to untangle settled facts, abandoned branches, tool noise, and current work.
handoff is a skill for the seam between sessions. Invoked with /handoff, it compacts the active conversation into a handoff document that a fresh agent can read to continue the work. Its design is intentionally selective: it carries the live thread, references durable artifacts instead of copying them, saves the document to the operating system’s temporary directory rather than the workspace, includes suggested skills, and redacts sensitive material.
The central idea is compaction. Preserve momentum, not every word.
Why session changes are a real engineering boundary
A context switch happens more often than teams admit. A long thread approaches a limit. Someone stops work for the day. A specialist agent completes research and another agent implements. A human changes the task’s priority. A review uncovers a concern that needs a new conversation.
Without an explicit handoff, the next participant must reconstruct intent from code and chat history. Code tells you what exists, not always why it was chosen. A ticket may state the desired outcome but not the current blocker. A plan may be accurate but not reveal which task was half-finished when the session ended. The handoff fills that narrow but valuable gap.
What belongs in a high-quality handoff
The live thread
State what is in flight in plain language. “Implementing organization invitations” is too broad. “Persistence and service-layer authorization are complete; email delivery remains unimplemented because the existing notification abstraction does not support signed links” is useful.
Why it matters now
Explain the immediate context: a test is failing, an API decision is pending, a migration must be reviewed, or a release is blocked. This helps the next agent choose the right first action rather than simply continuing the last visible edit.
Settled decisions
List only decisions the next session must not accidentally undo. Include the rationale briefly and point to the specification, ADR, issue, or code path that is authoritative. For example: “Invites expire after seven days; accepted in ADR-014. Do not change token model without product approval.”
Open questions and blockers
Be concrete about what is unresolved, who owns the choice, and what evidence is needed. “Need to decide email provider” is weak. “Choose whether to send through the existing asynchronous notification service or add a transactional provider; inspect incident history and delivery requirements first” gives the next agent a route forward.
References, not duplicates
handoff specifically avoids restating material already captured in a spec, plan, ADR, issue, commit, or diff. It references a path or URL instead. That is a safeguard against documentation drift. If a spec changes, the project has one source of truth rather than five copied versions in old handoff notes.
Why temporary storage matters
The skill saves handoff documents to the OS temporary directory, not the repository workspace. This is a useful design decision. A handoff is session glue, not necessarily a product artifact that should be committed, maintained, and discovered by every future developer.
That does not mean a handoff is disposable in the everyday sense. It may contain crucial information for the next session. It means it should not become another competing project document. Durable decisions belong in durable artifacts; the handoff points to them.
How to invoke it well
handoff is user-invoked rather than automatic. That is good: humans know when a transition is intentional. Pass a note describing what the next session is for so the document can be tailored to the continuation.
/handoff Next session will implement the API routes and integration tests for invitation acceptance. Preserve the settled authorization rules, current migration state, failing test details, and links to the approved spec and diff.
Enter fullscreen mode Exit fullscreen mode
A targeted instruction leads to a targeted note. “Summarize everything” tends to reproduce the problem handoff is designed to solve.
A usable handoff template
Objective
- What outcome are we delivering?
Current state
- What is complete? What is partially complete?
Settled decisions
- Decision, rationale, authoritative reference.
Open questions / blockers
- What is unresolved, who owns it, what evidence is needed?
Validation
- Commands run, test results, environment assumptions.
References
- Specs, plans, ADRs, issues, commits, diffs, relevant files.
Next action
- The first concrete thing the next agent should do.
Suggested skills
- Which skill or workflow should be used next?
Enter fullscreen mode Exit fullscreen mode
The template is deliberately operational. It gives a successor enough to act without pretending to be a full project history.
Example: weak versus strong
Weak: “Worked on auth. Some tests pass. Continue tomorrow.”
Strong: “Goal: add passwordless sign-in for existing users. Completed token persistence and expiry tests; API endpoint exists but is not wired to mail delivery. Decision: do not reveal whether an email belongs to an account see security section in docs/auth-spec.md. Blocker: current notification adapter cannot send template variables. Next: inspect adapter contract and propose the smallest compatible extension. Ran bun test auth: 18 pass, 2 skipped. Suggested skills: domain-model if adapter change affects notification domain; TDD for implementation.”
The strong version contains less total history but far more usable context.
Security and privacy
handoff is designed to redact secrets, passwords, API keys, and personally identifiable information. Do not treat automatic redaction as permission to paste secrets into a conversation. The safer practice is to reference secret-management locations and use neutral identifiers: “Production API credential is configured in the deployment secret store,” not the credential itself.
Also consider sensitive business context. A handoff can reveal incident details, customer behavior, or internal strategy. Keep it scoped to the recipient and store durable security findings in the appropriate controlled artifact.
Common mistakes
Turning the handoff into a transcript
Long chronological summaries force the next agent to reread history. Prefer current state, decisions, references, and next actions.
Failing to name the next action
A handoff that says “continue implementation” leaves the successor to choose a starting point. State the first file to inspect, command to run, or decision to obtain.
Duplicating the spec
Copying a plan makes it stale. Reference the canonical version and record only what changed in the live conversation.
Hiding uncertainty
Say when a conclusion is tentative. A false sense of certainty is more damaging than an explicit unresolved question.
Where handoff fits in an agent workflow
Use a planning skill to clarify a feature, a structured build workflow to implement it, concise execution mode when appropriate, and handoff at the transition point. Handoff is not a replacement for specs or commits. It is the bridge that makes those artifacts usable in the next context.
Bottom line
A good handoff lets a new agent inherit the work’s momentum without inheriting its noise. Capture the live thread, link the stable artifacts, make uncertainty visible, and state the next action. That is enough context to continue well and not so much that the next session starts by getting lost.