v1.0 handoff.skill

/handoff

A Claude skill that packs up everything you and Claude figured out in a session, so
the next session can pick it up and keep working. The next session can be a fresh
Claude Code window, a chat on claude.ai, or a completely different assistant like
ChatGPT or Gemini.

After creating this skill, research was done to find other similar handoff skills.
The two most popular, by Matt Pocock and ToolMonsters, plus a third by Ruben Hassid,
were each compared against this skill, and any positive attributes from them were
added to this already robust handoff skill.

More information can be found at the end of this readme regarding what positive
attributes were selected from each skill and then added to this build.

Full disclosure: Claude wrote quite a bit of this Readme, and a lot has been removed,
and some human adjustments have been made when the language was too robotic.

The skill itself has been checked for any security issues, but feel free to upload it
to Claude and have it check out the skill for you before you install it. It's a best
practice procedure to follow with any skill with a low GitHub star count like mine.

The problem

You work with Claude for two hours. You make decisions. You hit dead ends. You find
solutions that you'll forget ten minutes later. Then the chat gets too long, or it's
late, or you found a good stopping point and want to save on tokens.

Because you know that every question you ask, Claude rereads everything in that same
chat, eating your tokens, so you start a new chat. But, the new session knows nothing
of the previous chat. Ten minutes in, it suggests the exact approach you already
threw out, and rediscovers that setting the hard way.

The obvious fix is to ask for a summary. But a simple summary can get really messy,
really fast. There are miles of nuance in your chat. Things that you tried and found
were the wrong approach, and random solutions Claude stumbled across and you have no
idea how to put into words.
What the new session needs is a picture of what's true right now, plus, and most importantly,
the reasoning that isn't saved anywhere else.

That's what this skill writes... and more.

It's a way to start a fresh session with all of your progress intact. Every u-turn,
every discovery, every file needed to continue as if you just hit the reset button
on your token pool, and with the /handoff skill you're ready to keep going!

The idea behind it

Everything that went right is already saved in your files. The code is there. The
document is there. You don't need to write it down again.

Everything that went wrong only exists in the conversation, and the conversation
is what you're about to lose. The failed attempts. The moment you realized why
something wasn't working. The thing you nearly "fixed" that turned out not to be
broken.

That's the expensive knowledge, and it's the first thing an ordinary summary throws
away, because it looks like clutter. This skill goes looking for it on purpose.

What it does

• It checks the files before it trusts its memory.

• It reads the chat a second time before delivering. After drafting, it goes back
  for the things a first read misses: a correction you made once in passing, a limit
  you mentioned once and never repeated, and whether a file reference points at the
  current version. If two parts of the chat contradict each other and it was never
  settled, it lists that as an open question instead of picking a side.

• It asks where the handoff is going, and never assumes.

• It includes your actual work when the next session can't reach your files. More
  on this below, because it's the rule people ask about most.

• It says how sure it is about each thing.

• It won't make things up to look thorough.

• It copies names and numbers exactly.

• It removes passwords and personal details. It scrubs out "dangerous" information
  such as a password, an access key, or a real person’s email address. If it isn't sure
  whether something counts, it asks you instead of guessing. The next session learns how
  the thing works without inheriting your credentials.

• It separates facts that expire from facts that don't. When a session produces
  enough permanent knowledge (like setup quirks that cost you time, or a rejected idea
  likely to come up again), the skill writes a second, short file just for that.
  If there isn't enough, it says so in one line and skips the file. It also tells you
  where that file should live so it gets read automatically: as CLAUDE.md in your
  project folder for Claude Code, in Project knowledge on claude.ai, or in another AI's
  saved-instructions setting.

• It tells you which files to bring. A handoff that mentions screenshot-3.png
  is useless if the screenshot stays behind. So the list of files to bring goes in two
  places: inside the document, and as a plain checklist at the end of the chat reply,
  so you don't have to open the document to find out what to move. If the next session
  is a terminal tool other than Claude Code, the fingerprint script is on that list too.

• It won't overwrite your files without asking. If a file it wants to write already
  exists, like an older handoff or a CLAUDE.md, it checks with you first. For an existing
  CLAUDE.md, it shows you what it would add instead of replacing what's there.

• It keeps things short. Most handoffs land between 150 and 300 lines. Past about 500, it assumes it started
  telling the story of the session instead of describing where things stand and reevaluates
  what is going into the markdown document. However, pasted work is not counted in those
  numbers and is never shortened to fit them.

• It suggests you test the handoff. It recommends opening a fresh chat with
  nothing but the handoff, and watching whether the new session asks sensible
  questions or charges ahead on assumptions.

• It names other skills that would help. Taken from the comparison with Matt Pocock's
  handoff skill, because of his multiple skills he's created, it lists them and explains
  in one line what each one does, so the note still makes sense if the next session doesn't
  have that skill installed. It skips this entirely when you're heading somewhere that
  can't use Claude skills at all.

• It only runs when you ask. In Claude Code it won't offer itself, and it won't
  trigger because your conversation sounds like it's wrapping up. On claude.ai it may
  still start on its own, but nothing else changes, because the skill asks its questions
  out loud rather than relying on what you typed after the command. But to date, the skill
  has never fired for me without typing "/handoff" (without quotes) into the prompt field.

What's in the document

A single markdown file. It starts at its own heading and ends at the last section.
No "here's the handoff you asked for," no sign-off.

• Start here: where things stand in two or three lines, then the first action
• Paths and inventory: where everything lives, plus the companion files to bring
• Work in progress (verbatim): your actual draft or code, when the destination needs it
• What this thing is: just enough to get oriented, plus what must not be changed
• Environment notes: the settings, flags and quirks that cost you time to find
• Known broken: including anything written but never actually run, flagged clearly
• Decisions and rejected alternatives: what was chosen, and what was ruled out and why
• Open items, open questions, and how to verify a change
• Working preferences: how you like to be worked with, and corrections you've made
• Suggested skills: when the destination can use them
• Suggested opening prompt: a ready-to-paste first message for the new chat, when
  heading to claude.ai or another AI. Left out for Claude Code, which opens the file
  directly.

Empty sections get dropped rather than padded. Depending on the session you may
also get project-notes-<topic>.md, the permanent-knowledge file described above.
The main document is saved as handoff-<topic>-<YYYY-MM-DD>.md in your working
folder, not a temporary folder, so you can actually find it.

The verbatim rule, and how this skill handles it

"Verbatim" means word for word. Copying the real thing instead of describing it.

It matters because of how AI models behave. Hand one a description of your draft
and it will helpfully write a new draft. The new one will look fine. It will also
have quietly lost every deliberate choice you made, and neither of you will notice.

Some handoff tools solve this by always pasting everything, every time. This skill
does something slightly different: it asks where the document is going first, then
picks.

• Going to a new Claude Code session on the same computer? The document points
  at your files instead of copying them. The next session can just open them, and a
  copy would start going out of date the moment it was made.
• Going to claude.ai, or to ChatGPT, Gemini, or anything else? Your work gets
  pasted in whole. Those places can't reach your computer, so a file path is a dead
  end there.
• Don't know yet? It asks one simpler question: should your work be pasted in
  full, or just referenced by its file path? If you can't answer that either, it
  pastes everything. A document that's longer than it needed to be just wastes a
  little space. A document pointing at a file nobody can open
  has lost the one thing it was carrying.

Three more things protect that rule:

1. Nothing gets trimmed to hit a length limit. As mentioned, the pasted work
   sits outside the 150-to-300-line target. If a file is big enough that pasting it
   whole seems unwise, the skill stops and asks you rather than decidin...