Skill and subagent – splitting the work

Picture a kitchen with a single cook. The main AI is that cook, and the skill is its cookbook: it tells the cook how to make the whole dish. The trouble is that the cook works alone – peeling the carrots, stirring the soup so nothing sticks to the pot, and trying to keep an eye on the main course at the same time. The whole dish takes longer, and the cook’s attention is scattered, because everything has to be handled at once.

A subagent is our cook’s helper: a separate AI that the cook hands one specific job. The helper can work alongside the cook, and since you don’t have to be a master chef to peel carrots, a subagent can run on a smaller AI model than the cook does.

Let’s leave our imaginary kitchen and look at a real example. In the lesson on your first skill we built a skill that puts together a plan for the day each morning. There, one main AI had to do everything on its own: check the inbox and the calendar, and finally turn all of it into a plan. It did this in sequence, one job after another, and all on the same model the whole conversation ran on. A skill like that is a great candidate for handing part of the work to subagents: one goes to the inbox, the other to the calendar. The main AI then stays with the job that matters most – building the plan for the day from the data the subagents bring back.

Why split a skill into subagents at all

Haiku, Claude’s fast and inexpensive model, can go through the inbox and the calendar. Each source gets its own subagent running on Haiku. The first one goes through the inbox and lists the emails from the last 24 hours, one line each. The second goes through the calendar and lists today’s meetings. The main AI keeps working on a larger model, Opus or Sonnet for example: it decides what matters and builds the plan for the day from those two lists.

A subagent reads the emails or the calendar in its own context. What it hands back to the main conversation is only the result: one line per email instead of the full text of forty messages. That way the whole inbox and the whole calendar never take up room in the main conversation.

We suggest the simplest route here: pulling subagents out of a skill that already works. It isn’t the only one. You can define the subagents on their own straight away, without a skill, or design the skill together with its subagents from the start. Pulling them out of a finished skill is the easiest, because you can already see how each part of the skill behaves.

Measure the skill, then ask what to take out of it

The morning-plan skill already works. Open a new conversation, run the skill in it, and as soon as it finishes, type /context. Claude Code shows a coloured grid: what is taking up the context and how much room is still free. Take a screenshot – at the end of the exercise you’ll compare it with the state after the change.

Do all the further work on the subagents and the skill in that same conversation. Start with a review of the skill:

Read my morning-plan skill. List the parts that a separate subagent could carry out, and separately the ones that have to stay in the skill. For each part, say how much material has to be read to carry it out and how much of it ends up in the plan for the day.

The last sentence of the prompt shows which part is worth pulling out: one that reads a lot and hands little to the plan. Going through forty emails to sum up each one in a single line is that kind of part. Building the plan from ready-made lists isn’t, because that is the most important work and it stays with the main AI.

The “keep in the skill” list should include the step with the profil.md file. From the profile, the main AI knows what you do, and it uses that to decide which emails matter.

Set the model explicitly, because by default the subagent uses yours

A subagent is an ordinary text file with instructions, just like a skill. You don’t write the file by hand – ask Claude Code for it, starting with a subagent for the inbox:

Create a subagent called inbox-review, available in all my projects, based on the email step of the morning-plan skill. The subagent should list every email from the last 24 hours, one line per message: sender, subject and a short note on what it is about. It must not judge which emails matter – the skill makes that decision. Set its model to haiku, with no version number. Don't restrict its tools, because it needs access to the Gmail connector. Don't change the morning-plan skill yet.

The sentence about the model is the one that matters most here. At our training sessions, participants often leave it out because they assume Claude Code will give the subagent a smaller model on its own. Don’t count on that: without that sentence the subagent usually runs on the same model as the main conversation, and the saving is gone.

Open the subagent file once and see what was created. At the top there’s a header, similar to the one in a skill:

---
name: inbox-review
description: Lists the emails from the last 24 hours, one line per message.
model: haiku
---

The description field tells Claude Code when to hand work to this subagent. The model: haiku line is the sentence about the model from your request. Plain haiku, with no version number, moves on to newer Haiku models over time. A model written with a version number stays on that version until you change it.

If the header also has a line starting with tools:, the subagent gets only the tools listed there. Without the Gmail connector on that list, it can’t open the inbox. In that case, ask Claude Code to remove the line.

Choose the model from the bottom up: start with haiku. If the email summaries keep missing what the emails actually say, ask Claude Code to switch to sonnet.

See what the subagent should do and what it should hand back

Below the header of the subagent file are its instructions. Read them and check that they say two things.

First: what the list should look like when the subagent hands it back. It should have one line per email – the sender, the subject and a short note on what the email is about. This matters because that list is all that comes back to the main conversation. If the instructions don’t describe it, the subagent may return a single vague sentence, such as “the inbox has three enquiries and a few invoices”. The main AI can’t build a plan from a sentence like that.

Second: that the subagent doesn’t pick the important emails. The subagent lists all of them, and the main AI chooses the ones that matter. Only the main AI knows your profile, and it also sees the calendar. The subagent sees nothing but the inbox.

If something is missing from the instructions, ask Claude Code to add it.

You create the calendar subagent with a similar request:

Create a subagent called calendar-review, available in all my projects, based on the calendar step of the morning-plan skill. The subagent should list today's meetings, one line per meeting: time, title and a short note on what the event description says. It must not judge which meetings matter – the skill makes that decision. Set its model to haiku, with no version number. Don't restrict its tools, because it needs access to Google Calendar. Don't change the morning-plan skill yet.

Replace part of the skill with a hand-off

Now the email and calendar steps come out of the morning-plan skill, and hand-offs to the subagents take their place. Ask Claude Code to make the change:

In the morning-plan skill, replace the step that goes through my email with an instruction to have the inbox-review subagent list the emails from the last 24 hours. Add that the skill should wait for its list before it starts building the plan. Keep the decision about which emails need my reply in the skill. Also add that when the subagent's summary isn't enough to decide, the skill should read the whole email.

Replace the calendar step with a similar request:

In the morning-plan skill, replace the calendar step with an instruction to have the calendar-review subagent list today's meetings. Add that the skill should wait for its list before it starts building the plan. Also add that when the subagent's summary isn't enough to decide, the skill should read the full event description in Google Calendar.

The main AI reads a full email or a full event description only when the short line from the subagent isn’t enough. The first step, the one with the profil.md file, stays in the skill unchanged.

Run the skill again and check that the subagents did the work

Once the skill has been changed, open a new conversation, run the skill in it, and as soon as it finishes, type /context. Compare this grid with the screenshot from before the change. There should be more free space left.

A new conversation is essential here. In the conversation where the subagents were created, the grid would also show all of that work, and comparing it with the screenshot would tell you nothing.

If both grids look the same, check whether the skill really handed the work to the subagents. Ask Claude Code in the same conversation: “Did subagents go through my inbox and calendar, or did you do it yourself?” If it answers that it did it itself, ask it to fix the hand-offs in the morning-plan skill.

If the plan for the day came out weaker than before the change, check what the subagent handed back. After the skill runs you see the finished plan, not the subagent’s list, so ask for the list directly:

What exactly came back from the inbox-review subagent? Paste its final report without summarising it yourself.

If the report is empty or too vague, ask Claude Code to fix the instructions in the subagent file, not in the skill. Those instructions are what tell the subagent what to hand back.

Why the skill waits for the subagent’s result

In an ordinary conversation, Claude Code runs subagents in the background: they work alongside it, and the main AI gets the result when they finish. That’s why the hand-off in morning-plan says “wait for the lists before you start building the plan”. Without that sentence, the main AI could start on the plan before the subagents’ lists come back.

When a subagent’s result isn’t needed in the later steps – saving the finished plan to a file, for example – you can leave out the sentence about waiting. The skill then carries on, and the subagent finishes its work in the background.

What to take away from this lesson

• A smaller model has to be written into the subagent. Without it, the subagent usually runs on the same model as the main conversation, and the saving is gone.
• The subagent reads a lot and hands back a short list; the main AI decides. Going through forty emails and summing up each one in a line is work for a subagent; choosing what matters and building the plan stay in the skill.
• Pulling subagents out of a finished skill is the simplest route. It isn’t the only one: you can also create the subagents on their own straight away, or design the skill together with them.
• Only the final report comes back to the main conversation. That’s why the description of the result in the subagent file decides whether the skill has anything to work with.
• /context shows whether the change made a difference. Two measurements, each in its own new conversation: before the change and after it.

Tasks

Tick them off as you go. The state is stored in your browser, so you can come back to this list tomorrow.

• The morning-plan skill ready for the exercise
• A list of candidates to pull out, split into “for a subagent” and “keep in the skill”
• Subagents for the inbox and the calendar created, on the haiku model and with access to the connectors
• The description of the returned list checked in the subagent files, along with the sentence saying the subagent doesn’t judge what matters
• The email and calendar steps cut from the skill and replaced with hand-offs
• Context usage compared before and after the change
• The subagent’s result checked in the main conversation
• Checked that the skill waits for the subagents’ lists before it builds the plan