/handoff is my new favourite skill

0:00 A few weeks ago, I noticed myself doing something with agents that I thought was very clever, but I thought it was just too simple to require a skill. For those who don't know, I'm constantly thinking about skills. I'm constantly thinking about how to package my instincts and coding practices into reusable skills, and this has meant my skills repo has almost 100,000 stars at the time of recording. The skill that I started to think about was a handoff skill. And the theory was that this skill would take the context window of the current session and compress it down into a markdown file that could be handed off to another session. And so, a couple of weeks ago, I shipped this.

0:38 It's inside skills, inside productivity, and it's inside handoff here. And it's a very, very simple skill. It says to write a handoff document summarizing the current conversation so a fresh agent can continue the work. Save it to the temporary directory of the user's operating system, not the current workspace. I put this into my skills folder as an experiment to see how much I would use it. And it turns out I used it a lot. In this video, I'm going to show you a deep dive of the skill, kind of why I designed it, what is the point of it, how it compares to built-in tools in some of these harnesses like compact, and also how you can get the most out of it to make the most of your grilling sessions. And if you dig the kind of stuff I've been showing you, then you will love the course that I've put together, which is AI coding for real engineers. A two-week cohort for folks who want to use AI coding tools for shipping quality code, not slop. It starts on June the 1st. We're doing a discount right now. Get into the link below so you can check it out. Let's start first of all by explaining why I made this skill and how it differs from compaction, which you may have heard of before. When we're inside a session like this, a coding session, we essentially, as we, you know, converse with the agent, as it does tool calls, as it makes file edits, then this context window is going to be filled up and filled up with more and more stuff in it. More and more tokens will fill up the context window. Now, in the harness I use, Claude code, it's the context window is huge, right? You get 1 million tokens worth of context window, but there is actually a smart zone and a dumb zone in these context windows.

2:12 Early on in the context window, you are going to get much better performance from the agent because the attention relationships are not so strained there. Because there's much fewer tokens to calculate, fewer attention relationships between those tokens, then the agent's attention isn't so diffuse. In other words, it's better able to focus when there's less content in there. This means that as your conversation develops, you're going to get dumber and dumber and dumber responses from the agent all the way up to going up to, you know, 800,000 tokens, which personally I've never been in because around by the 120k token mark, I start to feel like I'm in the dumb zone. So, this means yes, that even though Anthropic advertises a ton of context window on these models, really for, you know, proper smart tasks, you've only got about 120k to work with, which means you need to budget really efficiently and you need to be aware of your context window at all times. So, the question then becomes, what do you do when you're starting to hit up against this dumb zone? How do you recover your conversation? How do you continue the conversation beyond the dumb zone while staying smart? And the answer to that is compact. What compact does is it will take a large conversation like this and summarize it, so you go essentially from near to the dumb zone to all the way into the smart zone here.

3:34 And there's even sometimes an auto compact buffer depending on what harness you're using and whether you've got it turned on, which means that when you're near to the end of the context window, let's say deep in the dumb zone, the auto compact buffer will kick in and automatically summarize your conversation inside a new session. This summary usually looks like the files reference, so it's just a list of files that have been referenced, the things that you said in the conversation are usually included, and the general tone of the conversation as well. This is then included as a little nugget at the start of the new session, and as you build up context in the new session, then you're continually referencing the old session. This means as you continue to compact and compact, you're going to end up with this kind of sediment of different layers here from previous conversations. And this can be a little bit inefficient, but it's also a decent way if you want to do certain types of sessions where you just need to barrel on on the same problem again and again and again. It can be really useful for debugging, actually, because you can compact all of the other options that you've tried, and then continue to try different things, hit the barrier, and then compact again to just save your state, essentially. So, it's a way of doing a long-running session, but it's only really one session. So, I continue to find compact a really, really useful tool for creating these long single sessions. But what I started to notice was I wanted to do other things with compact. I wanted to compact into another session. For instance, let's say I was in one session here, and while I was in this session, I noticed a little refactoring opportunity. Something that was totally out of bounds, out of scope for my current session, but I knew I would need to get there eventually. So, what were my choices? I could extend my current session, but then I would end up with this sort of like diluted context, where I was half working on one thing, half working on the other, and I would definitely hit the dumb zone, right? So, I probably wouldn't be able to finish my initial goal. I could compact, but then I would clobber all of the progress that I'd made in my current session, right?

5:37 What I really wanted to do was just say, "Okay, I want to complete this other thing in a separate session, and keep my current session pure." In other words, this was what I wanted. I wanted to essentially take the context or take just the slice that pertains to this extra bug fix, hand it off to another session, and then these two could just run independently. And so, for a while, what I was doing was saying, "Okay, take the stuff in my current session. I want to fix this particular bug. Write me a handoff.md document so that I can then just pass that into another agent." And it turned out I was doing this so freaking often that I just decided, "Okay, I need a skill for this." I most often use handoff while I'm grilling here. Here, I'm inside a grilling session that I did for planning some future features for Sandcastle, which is my sort of software factory. And what you can see here is that I'm kind of answering some questions. I'm only in Q2 of this grilling session, so not a long one. And I say here, "I think in future we may want to move the iterations and the completion signal onto a separate API. In fact, let's hand off that task to a separate agent." You can see here that when I'm defining handoff, when I'm saying, I'm saying the reason why I'm handing off and exactly what should be in that document. This does two things.

6:51 First of all, it actually sharpens the current grilling session I'm on. So, it says that given that constraint, Q2 collapses. So, it doesn't actually like it helps my current grilling session because I'm saying that's out of scope, we'll pick that up somewhere else. It then goes and creates a markdown file just here with the focus for the next session, file a GitHub issue, and eventually design for splitting iterations and the completion signal into a separate API. And then later, I just pass this into a another agent in order to create the issue. Simple.

7:20 Another pattern that I really strongly recommend is handing off during a grilling session to prototype. When you're grilling, when the agent is asking you questions from a grill me or grill with docs, which are more of my skills, you will often find there's two categories of questions you need to answer. There are the kind of known unknowns, the ones that the agent can ask you about, and then there's stuff that you really need to see in code or need to see prototyped. This can be really true with like UI prototypes or complicated bits of logic that you're not quite sure how to deal with yet. So, in this grilling session, we're down to question 13, actually, and we've got a sort of final resolution from the agent. And then we can see I say, "Hand off to prototype the difficult bits here, the window communication, the teal draw SDK integration," which was something I was building at the time. It creates the hand off, and then I go and implement the prototype on that branch.

8:14 So, in the prototype session, this ended up being a huge session, so 169 K tokens, so way bigger than would have fit inside the grilling. And what I did was I created this prototype of the UI and the kind of interaction that I wanted to see. And then I said, "Okay, let's hand this off back to the grilling session that spawned this. Take all of the learnings from the prototype, anything that's not directly captured in the prototype itself or that's non-obvious, give me a handoff document that I can pass back to the planner."

8:43 This is actually a really common pattern that I'm using here, where you have the initial session where you do some work, you hand off to another session, that session then creates another handoff document, and then passes it back to the original session. It's almost like you've done a kind of DIY sub-agent, where you're able to use a context window for one specific task, compress your learnings from that task, and pass it back to the parent. Then I was able to finish the grilling session and create some proper PRDs and issues with the prototype in there. So, it's incredibly rich pattern for actually getting what you need out of AFK agents and using prototypes. It's very, very cool. It's worth saying, too, that the thing that's cool about just using like a markdown documents here and not relying on kind of native agent stuff is that you can have this first session be Claude code, but you can just pass this to another agent, right? You can pass it to Codex or pass it to, you know, Copilot CLI, whatever you're using. So, if you want to do any kind of adversarial review or any kind of, you know, interaction between different coding agents, this is a very, very simple way to do it. We should also just read through the final bits of the skill here just so you understand the reasoning behind everything.

9:56 The theory here is include a suggested skill section in the document which suggests skills that the agent should invoke. I added this because sometimes it would I use skills to kind of define the flavor of that session and so having a suggested skill section means that you can kind of just paste the handoff document into the new session. It will invoke the skills needed like grill with docs or diagnose or prototype or something and then you're kind of good to go. So, you don't need to think about the skills that you need to use in the next session. It's pretty handy. Another one is do not duplicate content already captured in other artifacts. I would often find these handoff documents just got really big and they were just duplicating stuff that was already present either in other markdown files or in resources like GitHub issues or things like that. So, it's basically saying just use pointers instead of, you know, repeating everything that's in the documents. I also really strongly believe that you should save these handoff files to the temporary directory of the user's OS. In other words, these handoff files are disposable. They are not something to be kept around for a long time to rot in your code base's documentation. Another one is redact any sensitive information, API keys, passwords, or PII. This is, you know, pretty essential. You don't want these floating around in markdown files in just random places. And finally, if the user passed arguments, in other words, what the next session will be used for, treat those as a description as to what the next session will focus on and tailor the doc accordingly. I think of this is essential for handoff because in order to write a decent document, the agent needs to know what the next agent session is going to focus on. Every time I used handoff, I always describe the purpose, the reason that we're handing off because I just can't see how you would write a good handoff document otherwise. And of course, dictation makes this really easy cuz I just blast it out and then we're good to go. So, there we go. That's handoff. This is an essential skill in my toolkit that, you know, just like a lot of my other skills didn't exist but a few weeks ago. If you've been enjoying my skills, then you should check out the Cohort course. It is an absolute banger. We had about 2,500 people take it last time and I'm expecting, you know, a decent whack this time, too. Other than that, thank you so much for watching. My bookshelf behind me is filling up with new coding books that I'm going to be reading over the next couple of weeks. I'm thinking about maybe making a sort of what's on my bookshelf video of recommended books.

12:15 And I don't know. If you like that, then maybe give us a like and a comment or let me know what you want to see next. Either way, thanks for watching and I'll see you very soon.