handoff and to-questionnaire: pass context to another agent or person without losing anything

Sooner or later, work with an agent has to leave the session. Sometimes another agent continues it (in another tool, another folder, a fresh session). Other times what's missing is in the head of another person who isn't in the conversation. handoff and to-questionnaire are Matt Pocock's two skills for those two cases: one writes the context so someone else can continue, the other writes the questions so someone else can fill the gap.

This is part eleven of the Matt Pocock skills guide (mattpocock/skills repository, MIT license). Both are user-invoked.

Why they belong together

Both produce a portable Markdown document for a reader who wasn't in the conversation:

handoff: a document so another agent can continue

/handoff compacts the current conversation into a document so a fresh agent can continue the work. Its rules:

• It's saved to the OS temp directory ($TMPDIR, /tmp, or %TEMP% on Windows), not the project.
• It includes a suggested skills section: which skills the next agent should load.
• It doesn't duplicate: whatever is already in specs, plans, ADRs, issues, commits or diffs is referenced by path or URL, not copied.
• It redacts sensitive data: API keys, passwords and personal information.
• It takes an argument: "what will the next session be used for?". With it, the document focuses on what that session needs.

When to use it (and when not to)

ask-matt is precise here. At the boundary between phases you have five options: continue, /clear, /handoff, a subagent or /compact. /handoff is narrow: you only need it when you are:

• switching to a new harness (Claude Code to Codex, for example),
• moving to a new directory or repository,
• sending the work to a colleague,
• or forking a side task you found mid-phase without derailing what you're doing.

"That list is the whole clause." What /handoff buys is portability: a file that travels. If nothing is travelling, you don't need it. To stay in the same tool and folder, /compact is the default.

Its most characteristic use is the prototype flow from part 9: /handoff out to a new session in the prototype's folder, prototype there, and /handoff back with what you learned.

Primary and secondary sources

The repository explains the cost of any session switch with a useful idea: everything except continuing turns a primary source (the session as it happened) into a secondary source (a summary). The summary has less noise and more room to move, but it's lossy. The typical failure, per the author, is "a fresh session that is confidently wrong about a decision the summary flattened". That's why /handoff references the original artifacts instead of summarising them.

to-questionnaire: get what only another person knows

/to-questionnaire comes in when what blocks you isn't in your head or the code but in someone else's: the client who knows how they invoice, the accountant who knows the rules, the infrastructure lead who knows the expected load. The skill writes a questionnaire for that person to fill in on their own, or to fill in together over a meeting.

Grill the send, not the subject

It's the inverse of grill-me. Instead of interviewing you about the subject (which you can't answer, that's why you need someone else), it asks about the send, which you always know:

1. Who is it going to? Their role, expertise and relationship to you. This sets the tone and how much context the document must carry.
2. What do you need back? The specific decisions or facts you can't resolve alone.
3. Write the questionnaire, aimed at the gap between what that person knows and what you need, and report the file path.

The document's structure

• Title, purpose (why it exists and the decision riding on it), from whom to whom and how the answers will be used.
• Context: one paragraph to orient someone who wasn't in your head.
• How to answer: deadline, rough effort and an explicit invitation to say "I don't know" instead of skipping.
• Sections by theme, most important questions first (you may only get one pass). Each question is one idea, with an answer stub underneath and, only where needed, a one-line *why this matters*.
• Anything else?: a closing open question.

An example in the skill's format:

### How many subscribers do you expect in the first three months?

_Why this matters: it decides whether we start on the provider's free plan or a paid one from day one._

>

How they combine

Both close gaps the agent can't close from inside the session, and they fit the rest of the flow:

• What comes back from to-questionnaire is input material for grill-with-docs or to-spec. The answers resolve branches of the decision tree that were left open.
• If the questionnaire takes days to come back, /handoff saves where you were, with the questionnaire's path as a reference, so the session that receives the answers knows what to do with them.

A practical case: in the ebook example from part 3, the agent couldn't know the blog's real traffic or the exact fees. A questionnaire to whoever runs the analytics and the payments account, plus a /handoff with the session's state, closes that gap without losing the rest of the reasoning.

Common mistakes

• Using /handoff to stay in the same tool and folder. /compact or continuing is cheaper.
• Copying into the handoff what's already in an issue. Reference it, don't duplicate it.
• Compound questions in the questionnaire. "What load do you expect and in which region?" is two questions.
• Sending the questionnaire without context. Without the context paragraph, the recipient answers half the questions.

FAQ

Is the handoff saved in the repository? No, in the OS temp directory, to keep the project clean. If you need it elsewhere, move it yourself.

Can I use the questionnaire in a meeting? Yes: the skill allows for filling it in together live.

Is there an automatic version of handoff? in-progress/ has a beta skill, claude-handoff, that launches a background agent with claude --bg from the summary. It's not in the plugin.

Next step

Next time you're about to copy and paste a conversation into another tool, use /handoff with an argument saying what the next session is for. In part 12 of the guide we look at pr and wizard: how to present work in a pull request and how to walk a person through the steps the agent can't take.