--- title: What is an agent handoff file? slug: what-is-an-agent-handoff-file excerpt: An agent handoff file is a Markdown file an AI agent writes so the next session, or the next person, can pick up the work. Here is what one usually holds and how to read it fast. quickAnswer: An agent handoff file is a Markdown file that an AI coding agent writes at the end of a piece of work. It tells the next reader, human or agent, where things stand. A useful one names the goal, what was done, what changed, what is still open, and the next step. It often starts with a short YAML header that holds a status, a date and an owner. keyTakeaways: - A handoff file is a status report in Markdown, written by an agent for whoever picks up the work next. - The useful parts are the goal, what was done, files changed, open questions and the next step. - A YAML header with status, date and owner lets you judge the file before you read the body. - Read the open questions and next step first. That is where the agent needs something from you. - Handoffs get rewritten, so review what changed since your last read instead of starting over. publishedDate: 2026-10-05 dateModified: 2026-10-05 author: Bobby Huang cluster: A role: post status: published faq: - q: Is there a standard format for agent handoff files? a: Not one that every tool follows. Most handoffs share the same parts, though. You can ask your agent to use a fixed set of headings so every handoff reads the same way. - q: What is the difference between a handoff and a plan? a: A plan says what the agent intends to do. A handoff says what happened and what is left. You review a plan before work starts and a handoff after it stops. - q: Where should handoff files live? a: Somewhere both you and the agent can find them every time. Many people use one folder per project and name each file with the date and topic. related: - how-to-review-markdown-your-ai-agents-write - read-a-claude-code-plan-file-without-an-ide --- If you work with AI coding agents for more than one session, you start to see handoff files. An agent finishes a stretch of work and writes down where things stand. The next session reads it and carries on. So do you. This page explains what a handoff file is, what a good one holds, and how to read one quickly. It is part of a series on [reviewing the Markdown your AI agents write](how-to-review-markdown-your-ai-agents-write.md). ## A simple definition A handoff file is a Markdown file that passes work from one session to the next. It is often named `HANDOFF.md`. The writer is usually an agent. The reader can be you, another agent, or the same agent in a fresh session with no memory of the last one. That last case is why handoffs matter. A new agent session starts without the context of the old one. The handoff file is the context. ## What a handoff file usually holds There is no single standard. Still, useful handoffs tend to carry the same parts: - **Goal.** One or two lines on what the work is for. - **Status.** Done, in progress, blocked, or waiting on someone. - **What was done.** A short list, not a story. - **What changed.** File paths, settings, or records the agent touched. - **Open questions.** Things the agent could not decide alone. - **Next step.** The single next action, and who owns it. - **Checks run.** Tests, builds or commands the agent ran, with their results. Here is a short, made-up example. The paths are placeholders. > **Goal:** Add a dark theme to the settings page. > > **Status:** In progress. > > **What changed:** `src/settings/theme.css`, `src/settings/page.tsx` > > **Checks run:** Unit tests pass (42 of 42). > > **Open question:** Should the theme follow the system setting by default? > > **Next step:** Jane Doe answers the open question; then the agent wires the toggle. If a handoff is missing the open questions or the next step, ask the agent to add them. Those two parts save the most time. ## The header at the top Many handoffs start with a YAML front matter block. It sits between two `---` lines at the top of the file. A typical one holds a few fields: - `status: blocked` - `date: 2026-10-05` - `owner: Jane Doe` - `next: review the migration step` Read this first. In a few seconds you know whether the file needs you now. A raw YAML block can be hard to scan, though, especially when it grows to a dozen fields. The same fields read faster as a small table of keys and values. ## How to read a handoff in two minutes 1. **Header.** Check the status and the date. A stale date may mean a newer handoff exists. 2. **Open questions.** Answer them or note that you cannot yet. 3. **Next step.** Confirm you agree with it before the agent starts. 4. **What changed.** Skim the file list. Anything surprising deserves a closer look. 5. **Checks run.** A handoff that says "done" with no checks listed is a claim, not a result. You can skip the "what was done" list on a first pass. Come back to it if something in the steps above looks off. ## When the handoff gets rewritten Agents often update a handoff instead of writing a new one. That keeps one file per topic, which is good. It also means you may be reading a file that changed since you last looked. Rather than re-read it top to bottom, look only at what changed. If the file is in git, `git diff` on that file works. If not, keep a copy from your last read and compare it with `diff`. The guide on [reviewing agent Markdown](how-to-review-markdown-your-ai-agents-write.md) walks through both. > Ask your agent to keep the same headings in every handoff. Changes are much easier to spot when the shape of the file stays put. ## Handoffs, plans and receipts These three files often sit side by side: - A **plan** says what the agent intends to do. You review it before work starts. See [how to read a Claude Code plan file](read-a-claude-code-plan-file-without-an-ide.md). - A **handoff** says where the work stands and what is next. - A **receipt** records what was run and what came back, such as test results or ids. Same format, different jobs. Knowing which one you are reading tells you what to look for. ## Where Skimmark fits Skimmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. Planned for v1: Live Reload that keeps your place when an agent rewrites a file, a Changes View that shows what changed since you last looked, and a Frontmatter Table that shows the YAML header as key and value rows. The app itself has no AI features. To see what Skimmark is and follow along, visit [skimmark.com](https://www.skimmark.com/).