Handoff Writer

Write a handoff document summarising the current conversation so that a fresh agent — with no memory of any of it — can continue the work.

Derived from handoff by Matt Pocock (mattpocock/skills, MIT), which saves to the operating system's temporary directory. This version asks where to save instead, because the right place depends on how long the handoff needs to live and who else should see it. The rest of the instruction is his.

ASK BEFORE WRITING

Do not write the file until the destination is settled. Offer these, with the trade-off stated, and recommend the one that fits what the person just told you they are doing:

If they choose the repository root, offer to add the file to .git/info/exclude. That keeps git status clean without touching .gitignore, which would carry the entry to the remote and to everyone else. Use the common git directory, so the exclusion also applies in worktrees:

git rev-parse --git-common-dir

Append the file name there only if they say yes. It is per-clone and reversible; say so.

WHAT TO WRITE

Do not duplicate content already captured in other artifacts — specs, plans, ADRs, issues, commits, diffs. Reference them by path or URL instead. A handoff that restates a committed document goes stale the moment that document changes, and the reader cannot tell which copy is true.

Write down what exists nowhere else: the decisions taken and why, what was tried and abandoned, the state of anything half-finished, and the traps discovered along the way.

Include a suggested skills section naming which skills the next agent should call the Skill tool for.

Redact anything sensitive — API keys, passwords, tokens, personally identifiable information. A handoff is written to be read by someone who was not in the room.

If the user passed arguments, treat them as a description of what the next session will focus on, and tailor the document to that.

RULES

Ask where, every time. Not a default with a chance to object — a question with an answer. Even in the same project as last time: a handoff meant to survive a branch switch and one meant to be thrown away belong in different places.

Say what the file is for, inside the file. Whoever opens it may not know why it exists, and if it sits untracked in a repository root, whether it should be committed is the first question they will have.

State what is unfinished, plainly. The value of a handoff is concentrated in what is still broken. Ending on a summary of what went well wastes the reader's first minute.

Never write it unasked. The frontmatter disables model invocation on purpose.

EDGE CASES

Not inside a git repository. The repository-root option and the .git/info/exclude offer do not apply — say so rather than offering them and failing.

A handoff already exists at the chosen path. Ask before overwriting. The old one may describe a different piece of work, and losing it silently is the one failure this skill cannot recover from.

The conversation is short or the work is finished. Say so and write nothing. An empty handoff costs the next reader time and teaches them not to trust the next one.

The work spans more than one repository. Name every one, with its branch and its state. A handoff that describes a single repository when the work touched three is worse than none: the reader will act on the part it names.