8  Agent Skills 101: The Clear–Handoff–Notes Workflow

8.1 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.

8.2 The workflow: clear, handoff, notes

The core habit is three steps:

8.2.1 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.

8.2.2 2. Before you stop: handoff

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

Write a handoff note to notes/ summarizing what you did, what’s left, and any decisions you made.

The agent creates a short file — like notes/handoff-2026-09-29.md — capturing exactly what the next session needs to know.

8.2.3 3. Clear and continue

Run /clear (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.

8.3 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

8.4 What does NOT go in a handoff note

  • 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.”

8.5 Example

Here’s what a handoff note might look like:

# Handoff — 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
- Review setup chapter against latest participant-quickstart.md

## Decisions
- Dropped PDF/docx output for now — HTML only until content stabilizes
- Using parts in _quarto.yml to group chapters into sections

8.6 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.

8.7 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/:

  • Handoff notes (handoff-YYYY-MM-DD.md)
  • Plans and task lists for ongoing work
  • Analysis summaries from agent tasks (like the reproducibility analysis)

8.8 Branches and PRs

Once you’re comfortable with clear/handoff/notes, you can add git branches and pull requests to the workflow:

  1. Create a branch for a task
  2. Do the work (with clear/handoff as needed)
  3. Open a PR when it’s ready
  4. Merge and move on

This is a natural complement — the branch keeps your changes isolated and reviewable, and the handoff notes help you (or someone else) pick up the work if it spans multiple sessions. But the clear/handoff/notes habit is the foundation. Get that down first.