session-handoff

Write the state of the current session to a handoff file, so a fresh session can pick up from it. Run it before clearing context, switching tools, or passing work to another agent.

This skill is host-neutral. It runs on Cursor, Copilot, Codex, Claude Code, and any other Agent Skills host. It reads this conversation and a few git facts; it never reads an on-disk transcript.

Never block on I/O. Every read, list, and write here is best-effort. If a call is denied or fails, treat it as unavailable, do not retry, and do not guess another path. If the file cannot be written, the handoff goes in the chat reply.

Output contract (non-negotiable)

You are running session-handoff right now. These instructions are in your context because the skill was invoked, so write the handoff in this reply.

1. The file's first line is the resume stamp, exactly this shape: <!-- resume: <slug> | branch <branch> | head <short-sha> | <YYYY-MM-DD HH:MM> --> Outside a git repository use branch none | head none.
2. The file has these nine sections, in this order, as ## headings: Progress, Decisions Made, Rejected Alternatives, Files Touched, Verified vs Assumed, Do Not Redo, Issues / Blockers, Next Steps, Skills To Invoke. A section with nothing to say reads None.; never omit one.
3. The reply prints the file path and, on its own line, the resume phrase verbatim: Read <path> and continue from its Next Steps. with the real path. Then the constraint proposal (step 5), if any.
4. Never write a token, key, password, or connection string. Replace the value with a placeholder naming its kind, such as <api-token>.

Input

Steps

1. Stranded-work preflight

Before writing, check what would be lost, and put the findings under Issues / Blockers:

• Uncommitted files: git status --porcelain. List up to ten, then a count.
• Unpushed commits: git rev-list --count @{upstream}..HEAD. If the branch is ahead, state the count and the branch name. If there is no upstream, say so.
• Running background agents or jobs, only when the host exposes them. If the host has no such listing, skip this check without comment.

Run each command on its own, not chained. Outside a git repository, skip the git checks and say the state is not under version control.

2. Gather the session

From the conversation you already hold, collect: what was done and what remains, the decisions with the reason for each, the alternatives that were rejected and why, files changed, what was verified (a test passed, a command was run) versus only assumed, work that must not be repeated, and the next concrete steps.

Pointer, not copy. Refer to specs, plans, briefs, and commits by path or short SHA. Do not paste their contents. A handoff longer than about 150 lines usually copied something it should have pointed at.

3. Compose and redact

Fill the nine sections from references/handoff-template.md.

Then, before anything is written, scan what you are about to save for secrets: API tokens, keys, passwords, bearer strings, connection strings with credentials, private key blocks. Replace each with a placeholder naming its kind. The write in step 4 and the inline fallback both use this redacted text, so a secret is never on disk, even briefly.

4. Resolve the directory and write the file

Restated from the collection's shared conventions:

• Instruction file: the first existing of AGENTS.md, CLAUDE.md, .github/copilot-instructions.md. A line shippable-handoff-dir: <path> in it (relative to the repo root) overrides the handoff directory. Ignore a value that is absolute or contains .., and say so.
• Handoff directory: a path the user passed or named in the request, else the instruction-file override, else the first existing of .claude/handoff/, .agents/handoff/, docs/handoff/. When none exists, create .agents/handoff/ and suggest a gitignore line for it.
• File name: handoff-<slug>-<YYYYMMDD-HHMMSS>.md.

When the user's path is not one of the three defaults, the next session's session-primer will not find the file unless the instruction file names the directory. Offer the exact line shippable-handoff-dir: <path> with the constraint proposal in step 5, and write it only on a yes.

Write the redacted text from step 3.

Attempt the create and the write once. If the host denies either, do not retry, do not try another location, and print the whole redacted handoff in the reply instead, after a one-line note that the write was denied.

5. Propose reusable constraints

Look for rules this session learned that would apply again in this project, for example "run the formatter before the type check, the CI order depends on it". Propose at most three. Drop any candidate that names a single file, commit, or incident instead of a rule that holds next time.

Show each as the exact line you would add to the instruction file. Write nothing to the instruction file without a yes. Wait for it in the reply; an edit to that file is not part of the handoff. If nothing generalises, say so and offer no edit.

6. Reply

Print the file path, the resume phrase, a two-line summary of the Next Steps, and the constraint proposal. Nothing else.

Rules

• User-invoked only. Never start on your own because a session got long.
• The file is the product. The reply is short.
• Pointers over copies. Secrets never.
• Do not edit the instruction file, source, or any other file. The handoff and the proposal are the whole job.
• A denied write is printed inline once and not retried.
• In Skills To Invoke, list skills by name for the next session to call with the host's skill tool. Never tell it to run a user-invoked skill on the user's behalf.

Related

• Section guide and example: references/handoff-template.md