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 [snorts]
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.
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, 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. 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.
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? 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 pertain 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.
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.
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 uh 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 handoff, and then I go and
implement the prototype on that branch.
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."
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, um,
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.
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, um,
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.
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.