# Context Handoff

> Produce a structured handoff document that lets work survive a context reset, compaction, or a fresh session without losing the thread. Use when the user says "context handoff", "save context before compaction", "hand this off", or when an agent is approaching its context limit mid-task.

- Skill: `aimasteracc/context-handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aimasteracc/context-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aimasteracc/context-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aimasteracc (https://skillmd.com/u/aimasteracc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aimasteracc/context-handoff

---


# context-handoff — Survive a context reset without losing the thread

## Purpose

Long autonomous work outlives a single context window. When the window fills (or a session
ends), everything not written down is lost — and the next session re-derives it badly or not
at all. This skill captures the *minimum sufficient state* to resume cleanly: not a transcript
dump, but the working set a fresh agent needs to pick up exactly where this one left off.

## When to trigger
- The agent is nearing its context limit mid-task (don't wait for the panic — hand off early).
- A session is ending with work in progress.
- Handing a task from one agent/person to another.

## How to run

1. **Capture only the working set** — what's needed to *continue*, not a history of what happened.
2. **Write to a durable location**: `./.handoff/<task-slug>.md` (or a memory key the user names).
3. **Make the next step unambiguous.** The single most important field is "NEXT ACTION" — the
   very next concrete thing the resuming agent should do.
4. **Point to evidence, don't inline it** — file paths, line numbers, command outputs by reference.

## The handoff template

```markdown
# Handoff: <task>

## Goal (unchanged)
<the original objective, one or two lines>

## NEXT ACTION  ← start here
<the single concrete next step, specific enough to execute without re-reading everything>

## State / progress
- Done: <what's verified complete — with evidence: passing cmd, committed sha, rendered screen>
- In progress: <what's half-done, and exactly where it stands>
- Not started: <remaining scope>

## Key decisions & constraints
- <decisions already made and why — so they aren't relitigated>
- <hard constraints that must hold>

## Landmines / open questions
- <what bit me, what's fragile, what's still unresolved>

## Map (where things are)
- <file:line pointers, relevant commands, the 2–3 files that matter>
```

## Principles
- **Resumability over completeness.** A short doc that lets the next agent act beats a long one
  that buries the next action.
- **Evidence by reference.** Link to the passing command / commit / file:line; don't paste logs.
- **Decisions are state too.** Record *why*, so the resuming agent doesn't reopen settled questions.
- **Hand off early.** A clean save at 70% context beats a panicked one at 95%.

## Notes
- If a `.handoff/` for this task already exists, update it in place — keep one current handoff
  per task, not a pile of stale ones.
- Pairs with the `context-handoff` trigger inside `failure-mode-audit` mode #3 (context anxiety):
  the handoff is the mechanism that turns "nearing the limit" into a clean checkpoint, not a rush.