5 ms·

I wrote a skill called /handoff. Whenever a session is nearing a compaction limit or has served its usefulness, it generates and commits a markdown file explain

I wrote a skill called /handoff. Whenever a session is nearing a compaction limit or has served its usefulness, it generates and commits a markdown file explaining everything it did or talked about. It’s called /handoff because you do it before a compaction. (“Isn’t that what compaction is for?” Yes, but those go away. This is like a permanent record of compacted sessions.) I don’t know if it helps maintain long term coherency, but my sessions do occasionally reference those docs. More than that, it’s an excellent “daily report” type system where you can give visibility to your manager (and your future self) on what you did and why. Point being, it might be better to distill that long term cohesion into a verbose markdown file, so that you and your future sessions can read it as needed. A lot of the context is trying stuff and figuring out the problem to solve, which can be documented much more concisely than wanting it to fill up your context window. EDIT: Someone asked for installation steps, so I posted it here: https://news.ycombinator.com/item?id=47581936 https://news.ycombinator.com/item?id=47581936

david_allison 7mo ago
Is this available online? I'd love documentation of my prompts.
- sillysaurusx 7mo ago
  I’ll post it here, one minute. Ok, here you go: https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bfc08 https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bf... Installation steps: - In your project, download https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bfc08 https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bf... into .claude/commands/handoff.md - In your project's CLAUDE.md file, put "Read `docs/agents/handoff/*.md` for context." Usage: - Whenever you've finished a feature, done a coherent "thing", or otherwise want to document all the stuff that's in your current session, type /handoff. It'll generate a file named e.g. docs/agents/handoff/2026-03-30-001-whatever-you-did.md. It'll ask you if you like the name, and you can say "yes" or "yes, and make sure you go into detail about X" or whatever else you want the handoff to specifically include info about. - Optionally, type "/rename 2026-03-23-001-whatever-you-did" into claude, followed by "/exit" and then "claude" to re-open a fresh session. (You can resume the previous session with "claude 2026-03-23-001-whatever-you-did". On the other hand, I've never actually needed to resume a previous session, so you could just ignore this step entirely; just /exit then type claude.) Here's an example so you can see why I like the system. I was working on a little blockchain visualizer. At the end of the session I typed /handoff, and this was the result: - docs/agents/handoff/2026-03-24-001-brownie-viz-graph-interactivity.md: https://gist.github.com/shawwn/29ed856d020a0131830aec6b3bc29dc9 https://gist.github.com/shawwn/29ed856d020a0131830aec6b3bc29... The filename convention stuff was just personal preference. You can tell it to store the docs however you want to. I just like date-prefixed names because it gives a nice history of what I've done. https://github.com/user-attachments/assets/5a79b929-49ee-4614-8f42-e764793ace5e https://github.com/user-attachments/assets/5a79b929-49ee-461... Try to do a /handoff before your conversation gets compacted, not after. The whole point is to be a permanent record of key decisions from your session. Claude's compaction theoretically preserves all of these details, so /handoff will still work after a compaction, but it might not be as detailed as it otherwise would have been.
  - david_allison 7mo ago
    Oh wow, thank you so much!!!!!
  - cruffle_duffle 7mo ago
    Thanks!!!
  - creamyhorror 7mo ago
    I already do this manually each time I finish some work/investigation (I literally just say "write a summary handoff md in ./planning for a fresh convo" and it's generally good enough), but maybe a skill like you've done would save some typing, hmm My ./planning directory is getting pretty big, though!
  - addandsubtract 7mo ago
    Thanks! The last link is broken, though, or maybe you didn't mean to include it? Also, if you've never actually resumed a session, do you use these docs at some other time? Do you reference them when working on a related feature, or just keep them for keepsake to track what you've done and why?
    - sillysaurusx 7mo ago
      Thank you. It was just a screenshot of my handoff directory. I originally tried to upload to imgur but got attacked by ads, then uploaded to github via “new issue” pasting. I thought such screenshots were stable, but looks like GitHub prunes those now. It wasn’t anything important. I appreciate you pointing that out though. I just keep old sessions for keepsake. No reason really. I thought maybe I’d want them for some reason but never did. The docs are the important part. It helps me (and future sessions) understand old decisions.
dataviz1000 7mo ago
Did you call it '/handoff' or did Claude name it that? The reason I'm asking is because I noticed a pattern with Claude subtly influencing me. For example, the first time I heard the the word 'gate' was from Claude and 1 week later I hear it everywhere including on Hacker News. I didn't use the word 'handoff' but Claude creates handoff files also [0]. I was thinking about this all day. Because Claude didn't just use the word 'gate' it created an entire system around it that includes handoffs that I'm starting to see everywhere. This might mean Claude is very quietly leading and influencing us in a direction. [0] https://github.com/search?q=repo%3Aadam-s%2Fintercept%20handoff&type=code https://github.com/search?q=repo%3Aadam-s%2Fintercept%20hand...
- sillysaurusx 7mo ago
  I was reading through the Claude docs and it was talking about common patterns to preserve context across sessions. One pattern was a "handoff file", which they explained like "have claude save a summary of the current session into a handoff file, start a new session, then tell it to read the file." That sounded like a nice idea, so I made it effortless beyond typing /handoff. The generated docs turned out to be really handy for me personally, so I kept using it, and committed them into my project as they're generated.
  - dataviz1000 7mo ago
    Oh, so the word 'gate' is probably in the documentation also! I see. So this isn't as scary. Claude is helping me understand how to use it properly.
    - airstrike 7mo ago
      Why would it be scary? Claude is just parroting other human knowledge. It has no goal or agency.
      - fwipsy 7mo ago
        By that logic, nothing computers do is scary.
chermi 7mo ago
Did the same. Although I'm considering a pipeline where sessions are periodically translated to .md with most tool outputs and other junk stripped and using that as source to query against for context. I am testing out a semi-continuous ingestion of it in to my rag/knowledge db.
flashgordon 7mo ago
I've actually been doing this for a year. I call it /checkpoint instead and it does some thing like: * update our architecture.md and other key md files in folders affected by updates and learnings in this session. * update claude.md with changes in workflows/tooling/conventions (not project summaries) * commit It's been pretty good so far. Nothing fancy. Recently I also asked to keep memories within the repo itself instead of in ~/.claude. Only downside is it is slow but keeps enough to pass the baton. May be "handoff" would have been a better name!
DeathArrow 7mo ago
I think Cursor does something similar under the hood.
mlrtime 7mo ago
Wouldn't the next phase of this be automatic handoffs executed with hooks? Your system is great and I do similar, my problem is I have a bunch of sessions and forget to 'handoff'. The clawbots handle this automatically with journals to save knowledge/memory.
- dominotw 7mo ago
  when work on task i have task/{name}.md that write a running log to. is this not a common workflow?
tstrimple 7mo ago
I've got something similar but I call them threads. I work with a number of different contexts and my context discipline is bad so I needed a way to hand off work planned on one context but needs to be executed from another. I wanted a little bit of order to the chaos, so my threads skill will add and search issues created in my local forgejo repo. Gives me a convenient way to explicitly save session state to be picked up later. I've got a separate script which parses the jsonl files that claude creates for sessions and indexes them in a local database for longer term searchability. A number of times I've found myself needing some detail I knew existed in some conversation history, but CC is pretty bad and slow at searching through the flat files for relevant content. This makes that process much faster and more consistent. Again, this is due to my lack of discipline with contexts. I'll be working with my recipe planner context and have a random idea that I just iterate with right there. Later I'll never remember that idea started from the recipe context. With this setup I don't have to.

david_allison 7mo ago

Is this available online? I'd love documentation of my prompts.

sillysaurusx 7mo ago
I’ll post it here, one minute. Ok, here you go: https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bfc08 https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bf... Installation steps: - In your project, download https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bfc08 https://gist.github.com/shawwn/56d9f2e3f8f662825c977e6e5d0bf... into .claude/commands/handoff.md - In your project's CLAUDE.md file, put "Read `docs/agents/handoff/*.md` for context." Usage: - Whenever you've finished a feature, done a coherent "thing", or otherwise want to document all the stuff that's in your current session, type /handoff. It'll generate a file named e.g. docs/agents/handoff/2026-03-30-001-whatever-you-did.md. It'll ask you if you like the name, and you can say "yes" or "yes, and make sure you go into detail about X" or whatever else you want the handoff to specifically include info about. - Optionally, type "/rename 2026-03-23-001-whatever-you-did" into claude, followed by "/exit" and then "claude" to re-open a fresh session. (You can resume the previous session with "claude 2026-03-23-001-whatever-you-did". On the other hand, I've never actually needed to resume a previous session, so you could just ignore this step entirely; just /exit then type claude.) Here's an example so you can see why I like the system. I was working on a little blockchain visualizer. At the end of the session I typed /handoff, and this was the result: - docs/agents/handoff/2026-03-24-001-brownie-viz-graph-interactivity.md: https://gist.github.com/shawwn/29ed856d020a0131830aec6b3bc29dc9 https://gist.github.com/shawwn/29ed856d020a0131830aec6b3bc29... The filename convention stuff was just personal preference. You can tell it to store the docs however you want to. I just like date-prefixed names because it gives a nice history of what I've done. https://github.com/user-attachments/assets/5a79b929-49ee-4614-8f42-e764793ace5e https://github.com/user-attachments/assets/5a79b929-49ee-461... Try to do a /handoff before your conversation gets compacted, not after. The whole point is to be a permanent record of key decisions from your session. Claude's compaction theoretically preserves all of these details, so /handoff will still work after a compaction, but it might not be as detailed as it otherwise would have been.
- david_allison 7mo ago
  Oh wow, thank you so much!!!!!
- cruffle_duffle 7mo ago
  Thanks!!!
- creamyhorror 7mo ago
  I already do this manually each time I finish some work/investigation (I literally just say "write a summary handoff md in ./planning for a fresh convo" and it's generally good enough), but maybe a skill like you've done would save some typing, hmm My ./planning directory is getting pretty big, though!
- addandsubtract 7mo ago
  Thanks! The last link is broken, though, or maybe you didn't mean to include it? Also, if you've never actually resumed a session, do you use these docs at some other time? Do you reference them when working on a related feature, or just keep them for keepsake to track what you've done and why?
  - sillysaurusx 7mo ago
    Thank you. It was just a screenshot of my handoff directory. I originally tried to upload to imgur but got attacked by ads, then uploaded to github via “new issue” pasting. I thought such screenshots were stable, but looks like GitHub prunes those now. It wasn’t anything important. I appreciate you pointing that out though. I just keep old sessions for keepsake. No reason really. I thought maybe I’d want them for some reason but never did. The docs are the important part. It helps me (and future sessions) understand old decisions.

dataviz1000 7mo ago

Did you call it '/handoff' or did Claude name it that? The reason I'm asking is because I noticed a pattern with Claude subtly influencing me. For example, the first time I heard the the word 'gate' was from Claude and 1 week later I hear it everywhere including on Hacker News. I didn't use the word 'handoff' but Claude creates handoff files also [0]. I was thinking about this all day. Because Claude didn't just use the word 'gate' it created an entire system around it that includes handoffs that I'm starting to see everywhere. This might mean Claude is very quietly leading and influencing us in a direction. [0] https://github.com/search?q=repo%3Aadam-s%2Fintercept%20handoff&type=code https://github.com/search?q=repo%3Aadam-s%2Fintercept%20hand...

sillysaurusx 7mo ago
I was reading through the Claude docs and it was talking about common patterns to preserve context across sessions. One pattern was a "handoff file", which they explained like "have claude save a summary of the current session into a handoff file, start a new session, then tell it to read the file." That sounded like a nice idea, so I made it effortless beyond typing /handoff. The generated docs turned out to be really handy for me personally, so I kept using it, and committed them into my project as they're generated.
- dataviz1000 7mo ago
  Oh, so the word 'gate' is probably in the documentation also! I see. So this isn't as scary. Claude is helping me understand how to use it properly.
  - airstrike 7mo ago
    Why would it be scary? Claude is just parroting other human knowledge. It has no goal or agency.
    - fwipsy 7mo ago
      By that logic, nothing computers do is scary.

chermi 7mo ago

Did the same. Although I'm considering a pipeline where sessions are periodically translated to .md with most tool outputs and other junk stripped and using that as source to query against for context. I am testing out a semi-continuous ingestion of it in to my rag/knowledge db.

flashgordon 7mo ago

I've actually been doing this for a year. I call it /checkpoint instead and it does some thing like: * update our architecture.md and other key md files in folders affected by updates and learnings in this session. * update claude.md with changes in workflows/tooling/conventions (not project summaries) * commit It's been pretty good so far. Nothing fancy. Recently I also asked to keep memories within the repo itself instead of in ~/.claude. Only downside is it is slow but keeps enough to pass the baton. May be "handoff" would have been a better name!

DeathArrow 7mo ago

I think Cursor does something similar under the hood.

mlrtime 7mo ago

Wouldn't the next phase of this be automatic handoffs executed with hooks? Your system is great and I do similar, my problem is I have a bunch of sessions and forget to 'handoff'. The clawbots handle this automatically with journals to save knowledge/memory.

dominotw 7mo ago
when work on task i have task/{name}.md that write a running log to. is this not a common workflow?

tstrimple 7mo ago

I've got something similar but I call them threads. I work with a number of different contexts and my context discipline is bad so I needed a way to hand off work planned on one context but needs to be executed from another. I wanted a little bit of order to the chaos, so my threads skill will add and search issues created in my local forgejo repo. Gives me a convenient way to explicitly save session state to be picked up later. I've got a separate script which parses the jsonl files that claude creates for sessions and indexes them in a local database for longer term searchability. A number of times I've found myself needing some detail I knew existed in some conversation history, but CC is pretty bad and slow at searching through the flat files for relevant content. This makes that process much faster and more consistent. Again, this is due to my lack of discipline with contexts. I'll be working with my recipe planner context and have a random idea that I just iterate with right there. Later I'll never remember that idea started from the recipe context. With this setup I don't have to.