ITMay 23, 2026

Don't Lose Your Work to /clear — Meet session-handoff

Every time you clear your AI agent's context, you lose hours of working knowledge that isn't captured in code or git history. session-handoff is a small skill that rescues the non-replaceable slice before it disappears.

By Andrea Borghi
Don't Lose Your Work to /clear — Meet session-handoff

Don't Lose Your Work to /clear — Meet session-handoff

If you have ever finished a long debugging session, hit /clear, and then a week later wished you remembered which of the three database options the team had ruled out — this is for you.

The problem is small but expensive. Working with an AI agent on a real project produces a layer of knowledge that lives nowhere else. Why a particular library was rejected. Which staging environment is broken. What the user actually meant by "the gate." It is not in the code. It is not in git. It is in the conversation. And the conversation is about to be erased.

The rescue test

session-handoff is a small Agent Skill that runs before you clear. It scans the session for facts and applies one decisive question:

"Would re-reading the repo recover this?"

If yes, drop it — the code is the source of truth. If no, it might be worth saving. That single heuristic eliminates roughly 80% of false saves and keeps the long-term memory file from turning into noise.

How it works in practice

The flow is seven steps but the experience is two: type a trigger like "checkpoint before clearing," review what would be saved, approve. The skill then writes structured markdown entries — user for role and environment, feedback for working rules, project for goals and decisions, reference for external system pointers — and updates a one-line index file so future sessions load it cheaply.

Two technical details that make this actually usable:

  • Date normalization. "Thursday" gets converted to 2026-05-21 at extraction time, so the entry still makes sense in three months.
  • Why / How structure. Every feedback or project entry includes the reason (often a past incident) and when the rule applies. That lets a future you judge edge cases instead of following the note blindly.

Who needs this

If your work touches long-running migrations, multi-stakeholder rollouts, or anything where verbal agreements outlive the conversation that produced them — this is the thing. Platform leads, SREs, contract engineers handing off work. Not because it is clever. Because the alternative is reconstructing what you already knew, badly, three weeks too late.

The repo is open and the skill is small enough to read in one sitting:

👉 github.com/andreab67/agent-skills/blob/main/session-handoff/SKILL.md

← Back to Blog