handoff: Give the Next AI Agent the Context It Actually Needs

AI-assisted engineering often fails not because an agent loses all context, but because a new session receives the wrong type of context. Giving too little context leads to repeated discovery and reopened decisions, while providing an entire transcript causes confusion over settled facts and current work. The handoff skill is designed to address this issue, creating a compact handoff document that a fresh agent can use to continue work.

This skill is selectively designed, carrying live threads, referencing durable artifacts, saving documents to the temporary directory, including suggested skills, and redacting sensitive information.

Session changes occur frequently, and without an explicit handoff, the next participant must reconstruct the intent from code and chat history. Code reveals what exists, not always why it was chosen. A ticket may state the desired outcome but not the current blocker, making it difficult for the next agent to choose the right first action.

The handoff fills this gap by providing what is in flight in plain language, explaining the immediate context, listing settled decisions with rationale and authoritative references, outlining open questions and blockers with specific details, referencing only paths or URLs instead of duplicating material, and saving handoff documents to the OS temporary directory rather than the repository workspace.

To invoke the handoff skill well, it should be user-invoked rather than automatic, as humans know when a transition is intentional. A note describing the purpose of the next session should be passed so the document can be tailored accordingly. A targeted instruction leads to a targeted note. A usable handoff template includes the objective, current state, settled decisions with rationale and references, open questions or blockers with needed evidence, validation commands and test results, references to specs, plans, ADRs, issues, commits, diffs, and the next action as well as suggested skills.

This template provides enough information for the successor to act without reproducing the entire project history.