Agent Skills 101: The Clear–Handoff–Notes Workflow

The problem

AI coding agents don’t remember anything between sessions. When you start a new session — or run /clear — the agent has no idea what you were doing five minutes ago. It starts fresh every time.

You might think the solution is to build up a huge memory file that the agent loads at the start of every session. But that creates its own problems: the file gets long, stale, and full of context the agent doesn’t need for the current task. It wastes budget re-reading old information.

There’s a simpler approach.

The workflow: clear, handoff, notes

The core habit is three steps:

1. Work on a task

Start your agent and give it something to do. As it works, it builds up conversation context — the files it has read, the decisions it has made, the changes it has written.

2. Before you stop: handoff

When you’re done with a task (or switching to something else), tell the agent:

I am about to clear.

If you set up your instructions in Skills 100, that phrase is enough: the agent commits loose ends and updates notes/handoff.md. Without it, spell it out:

Update the handoff note in notes/handoff.md with what we did, what’s left, and any decisions we made.

There is one handoff file, and the agent rewrites it each time, so it always describes where things stand now. Git keeps the old versions.

3. Clear and continue

Run /clear (it works in both Claude Code and Antigravity), or close the session. The conversation context is gone, but the handoff note is on disk.

Next time, start the agent and say:

Read the notes in notes/ and pick up where we left off.

The agent reads the handoff, gets oriented, and continues the work.

What goes in a handoff note

Good handoff notes are short and specific:

  • What was done (in a sentence or two)
  • What’s next (the immediate next step)
  • Any decisions made that aren’t obvious from the code
  • Blockers or open questions

What does NOT go in a handoff note

  • Long detail on one topic — put that in its own file in notes/ and point to it from the handoff
  • Entire file contents — the agent can read files itself
  • Code dumps — the code is in the repo
  • Full project history — keep it to what’s relevant right now
  • Anything the agent can figure out by looking at the repo
Tip

Think of a handoff note like a sticky note for a colleague: “I finished X, next step is Y, watch out for Z.”

Example

Here’s what a handoff note might look like:

# Handoff

Updated 2026-09-29.

## Done
- Set up Quarto book structure for clinic docs
- Wrote first drafts of setup and models chapters

## Next
- Write the "What Is Agentic Coding?" chapter
- Check the setup chapter against the hub's current sign-in steps

## Decisions
- Dropped PDF/docx output for now — HTML only until content stabilizes
- Using parts in _quarto.yml to group chapters into sections
- Why we chose HTML only: see notes/output-formats.md

Why /clear matters

Every message you send includes the entire conversation so far. As the conversation grows, each request sends more tokens and costs more. Running /clear resets this — your next request is cheap again.

The handoff note means you don’t lose anything important. You trade a long, expensive conversation for a short, focused one with a lightweight file to get the agent back up to speed.

The notes/ directory

Keep handoff notes and working notes in a notes/ directory in your project. This keeps them separate from your actual project files and easy to find.

Some things that work well in notes/:

  • The handoff note (handoff.md), kept short
  • Topic notes the handoff points to (notes/output-formats.md, notes/data-sources.md)
  • Plans and task lists for ongoing work
  • Analysis summaries from agent tasks (like the reproducibility analysis)

Branches and PRs

Clear–handoff–notes fits inside the branch-and-PR workflow from Skills 100:

  1. “I am starting a new task”: the agent makes an issue and a branch
  2. Do the work. Say “I am about to clear” and /clear as often as you need; the handoff note is committed on the branch, so the next session picks it up
  3. “Task is done”: the agent opens a PR and asks before merging

The branch keeps the changes isolated and reviewable. The handoff note lets you, or someone else, pick up work that spans several sessions.