# Handoff

> Save a resume-ready snapshot to context.md §0 so a FRESH agent (no memory of this session) can pick up exactly where this one left off. Use when wrapping up or terminating a Claude Code session, or when the user says "save context", "checkpoint", "hand off", or "I'm closing this session".

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

---


# Handoff — checkpoint the session into context.md

Your job: distill everything a brand-new agent would need to continue this work,
and write it as a new dated entry at the TOP of **`context.md` → §0 Current
status (most recent first)**. The next agent reads `context.md` first (it's
`@`-imported by `CLAUDE.md`), so this is the durable handoff channel — not your
chat history, which is gone the moment the session ends.

Write for someone with **zero context**. If a fact lives only in your head right
now, it must end up in the entry.

## 1. Gather the state (don't skip — read, don't guess)

Run these and read the output before writing:

```bash
git status --short            # uncommitted / untracked work
git log --oneline -8          # what landed this session
git branch --show-current     # are we off main?
git stash list                # anything parked?
```

Then assemble, from this session:

- **What changed & why** — the work done and the *reasoning/decision* behind it
  (the "why" is the part that's impossible to reconstruct from a diff).
- **State of the work** — committed+pushed? committed-not-pushed? uncommitted in
  the working tree? mid-refactor with the build red? Say exactly which.
- **Where it stopped** — if anything is half-done, name the file + the next edit.
- **Next steps** — the ordered TODO the fresh agent should start on.
- **Open questions / blocked on the human** — decisions awaiting the user, with
  the options on the table.
- **New gotchas** — traps you hit that aren't obvious from the code.
- **Verification status** — what you actually tested (build/lint/runtime/live) vs.
  what you only assumed. Be honest; an untested claim mislabeled as done is worse
  than no claim.

## 2. Write the entry

Prepend a new bullet as the **first `-` item** in §0 — directly after the line
ending `…these surfaces now exist:` and above the current top bullet.

Match the existing house style exactly:
- **Bold lead-in** summarizing the change, then `(newest, YYYY-MM-DD)` using
  **today's absolute date** (convert any relative date; check the environment's
  current date — don't hardcode).
- Tight prose. Backtick file paths, ops, and identifiers.
- End with the relevant tags when they apply:
  - `Touched:` — comma-separated files you changed.
  - `Next:` — the ordered next steps.
  - `⚠️` — any new gotcha or "blocked on the human" note.
  - `Supersedes` — if this overrides something in §1–§7, say so (those sections
    aren't always updated in-place).

Then **fix the `(newest)` marker**: remove or downgrade it on the previous top
entry so only one bullet is tagged newest.

Template:

```markdown
- **<one-line summary of the change>** (newest, YYYY-MM-DD). <2–5 sentences:
  what changed, why, and the state of it (pushed / uncommitted / WIP-build-red).>
  Touched: `path/a.ts`, `path/b.tsx`. Next: <ordered steps>. ⚠️ <gotcha or
  what's blocked on the human, if any>.
```

## 3. Compact context.md (always check, act on thresholds)

`context.md` is a status board, not an archive — and it's re-read at every
session start, so its size is a recurring cost. After writing the new entry,
measure it:

```bash
wc -c context.md                 # bytes
grep -c '^- \*\*' context.md     # rough §0 entry count
```

**If §0 has more than 8 entries, or the file exceeds 25 KB, compact now** (don't
defer it to a "later" that never comes):

- Keep the **newest 3 entries verbatim**.
- For each older entry that is fully landed or superseded:
  1. Move any still-true durable fact (architecture, gotcha, decision + its
     "why") into the right stable section (§1+).
  2. Then collapse the entry to a single line — or delete it outright if it
     carries nothing not already recorded elsewhere.
- **Never drop:** unresolved ⚠️ / blocked-on-human notes, claims still marked
  *assumed* (unverified), or the only record of why a decision was made.

Report the result in the end-of-handoff summary: `context.md: 11 entries /
34 KB → 5 entries / 18 KB` (or "no compaction needed").

## 4. Persist it

- **Never** write secrets, tokens, API keys, or `.env` values into the doc — secrets belong in the project's own secret store, not here.
- The handoff is only useful if it's committed (a fresh clone / new agent reads
  the committed file). Commit **and push**, ending the message with the
  `Co-Authored-By` trailer. **Where to push:** if the project auto-deploys its
  main branch (Vercel git integration — the default in this workflow), push
  `main` only when the session's work is verified and fit to be live; otherwise
  push a work-in-progress branch so the handoff is backed up without publishing
  unfinished work. Commit the `context.md` update plus any genuinely-finished
  work; for deliberately in-progress code, do **not** force a commit — instead
  make sure the entry describes its exact state so it can be resumed.
- After writing, show the user the new §0 entry and a one-line summary of what you
  committed/pushed vs. what's left in the working tree.