create-agent-handoff

Agent Handoff

When this skill is activated, capture the current session state and write a HANDOFF.md file to the project root so another agent can take over without losing context.

Clarifying Questions

Before writing the handoff, ask the engineer the following questions. Skip any already clearly answered in the conversation. Wait for the answers before proceeding.

1. Are there open tasks that should be marked as higher priority than others for the incoming agent?
2. Is there anything important from this session that is not visible in the git diff or conversation history — decisions made verbally, constraints discovered, things deliberately left out?
3. What is the single most important thing the incoming agent should do first?

Steps

1. Run git status and git diff to identify all changed, added, and deleted files
2. Check for any existing task lists, TODO comments, or open issues in the codebase
3. Summarize the goal and what has been accomplished based on the current conversation context
4. Write HANDOFF.md — overwrite if it already exists

Output

Write a file called HANDOFF.md in the project root with the following sections:

1. Goal

What was the overarching objective of this session? One short paragraph.

2. Completed

What has been done so far? Bullet list with file references (relative paths, line numbers where useful).

3. Changed Files

A table of all files modified, added, or deleted in this session:

File	Change	Notes
path/to/file.ts	modified	Brief note on what changed and why

Base this on git status and git diff output.

4. Open Tasks

What still needs to be done? Bullet list, ordered by priority if possible.

5. Next Steps

The single most important next action for the incoming agent. Be specific — include file paths and what exactly needs to happen.

6. Context & Decisions

Important decisions, constraints, or trade-offs made during this session that the next agent needs to know. Only include what is non-obvious or not visible from the code.

Rules

• Only document what actually happened — do not speculate or invent
• HANDOFF.md must be fully self-contained: a fresh agent with no conversation history should be able to read it and continue immediately
• Overwrite any existing HANDOFF.md — do not append
• Use relative file paths throughout
• Keep each section concise but complete — this is a briefing, not an essay