Introduction to Subagents: teaching notes
Side-by-side notes for 09-praxis-introduction-to-subagents.html (7 slides). This is a technical course with one plain-English heart: delegation. A subagent is a bounded job handed to a focused junior who goes away, works in their own space, and brings back the answer, not the mess. That translates cleanly for non-technical people, so keep the framing on the supervisor mindset, not the engineering. This is the first taste of the Praxis "Frontier" idea: managing a small team of agents instead of doing every step yourself. The deck is what the room looks at; this is what you say, where you stop, and how each idea lands for the person in front of you. Written from the deck and 09-introduction-to-subagents-lessons.txt, against the Praxis teaching library. Method: teaching-notes-method.md.
How to use these notes
- Blocks marked Back to your card, Brief it like a new hire and Run it live are the three moves from T0, how we teach Praxis. Use the names and tasks on the group's Use Case Cards wherever you see [name].
- These are guidance, not a script. Teach the person, not the slides.
- Each teaching slide has a Pause, then ask block. Put the question, then stop. Do not fill the silence. If they freeze, one line: "Take your time, type anything when you're ready, including 'I don't know'." Then wait again.
- By background gives you a line per archetype (from
tutor/scenarios.md). Reach for the one that matches whoever is in the room and ignore the rest. They are a palette, not a checklist to read out. - The backbone question for the whole course is the same one every time: "what would you send a subagent to go and do?" Keep returning to it. The whole course is one act of judgment: what to delegate, and what to keep in your own hands.
- This course names a command (
/agents) and a config file. Say them; do not read the YAML aloud (framings.md: voice). The point of every line is the outcome, not the keystroke. - Slide 4 (the config file) is mechanical and the same for everyone, so it carries one shared example, not nine. Said so on the slide.
- Hold the voice (
train-the-trainer.mdPart 4): no "great question", no emoji, one term only: Claude Code. Underclaim. Cost is "about twenty dollars a month" and stop. - This sits downstream of Claude Code 101 (course 02, slide 11 introduced subagents in one line). If the room has done it, this is the deep dive on that slide. If not, plant the bridge: you already keep a clean desk by sending the digging elsewhere; here's how.
Send the heavy lifting to a subagent
Set the frame: four ideas, one per screen, and the watching is the lesson. The whole course is about one managerial instinct: knowing what to hand off. You are not going to lecture; you are going to show, then hand it back to them.
"Four ideas, one screen each. The whole thing is about delegation, the oldest management skill there is, now pointed at a tool. You learn what to send away, how to brief it, and when not to bother. I'll show you each piece, then stop and ask where it fits your work."
The task they named in intake, and the moment in it where they go digging: opening file after file, tab after tab, to surface one fact. That digging is what a subagent is for. Promise you'll come back to it on the decision slide.
The whole course on one screen
Four moves: understand what a subagent is, build one, design it well, then judge when to reach for it at all. The last move is the one that matters; the rest serve it.
"Here's the whole thing on one screen. We meet the idea, we build one, we make it sharp, then we learn the judgment call: when it actually helps and when it gets in the way. If you lose the thread, this is the map back."
Don't teach the spine, just orient. The centrepiece is slide 6, the decision rule. Twenty seconds, then move.
A subagent works in its own context
A subagent is a focused helper that gets a role and a task, does the messy work out of sight in its own memory, and hands back only the answer. The intermediate steps (the file reads, the searches) stay isolated and never clutter your main thread. The tradeoff: you lose sight of how it got there.
"Picture asking a researcher to go find one thing. They open twenty tabs, read for an hour, then come back and tell you the answer in a sentence. You never see the twenty tabs. That's a subagent: it goes off into its own space, does the digging, and brings back just the result. Your own desk stays clear." (Plain framing carried over from 02-claude-code-101-teaching-notes.md slide 11: a researcher who returns one paragraph, not their twenty open tabs. Pairs with framings.md: context window: your working memory has an edge, and this is how you keep the noise off it.)
- "What's a piece of digging you do where twenty things get read and only one line of it matters to you?"
- "If someone could go do exactly that and bring back just the answer, what would you hand them?"
(wait)
- Investigator
- "find every mention of this entity across the whole file set": the hits, not the reading.
- Analyst
- "which of these responses left the pricing question blank?": the list, not the trawl.
- Designer
- "scan competitor campaigns before this pitch": the summary, not the tabs.
- Knowledge worker
- "which suppliers in this folder use a non-standard invoice format?": just the answer.
- Reporter
- "who hasn't filed an update this week?": the names, not the inbox sweep.
- Content
- "what have we already published on this topic?": the shortlist, cited.
- Form-filler
- "which receipts don't match any section of the template?": the flagged set.
- Outreach
- "pull the latest on this prospect before I write": the brief, not the search history.
- Exec
- "which retainers come up for renewal this quarter?": the list, sourced.
On the map: the new hire bringing in their own helper for the digging. The helper works at their own desk and brings back one page. You don't see their notes.
- Which part of your card is "read twenty things, one line matters"?
Name the tradeoff honestly: you get the answer without the journey, which also means you don't see how it got there. For high-stakes work, that's the reason you later ask it to cite sources and you verify the load-bearing facts. (objections.md: hallucinate / make stuff up: the answer comes back, you still check the claims that matter.) The built-in helpers are worth naming once: a general-purpose agent, Explore for fast search, Plan for plan-mode research. You may already be using them without knowing it.
Make one with /agents, Claude writes the file
You don't hand-code a subagent. You run /agents, describe what you want, and Claude generates it: a name, a description, the tools it can touch, the model, and a system prompt that is just plain-English instructions. It's a Markdown file with a short header. Scope it to one project or to everything you do.
"You build one by talking, not by coding. You run /agents, say 'I want a helper that reviews my work for X', and Claude writes the whole setup for you. The one part worth understanding is the description. That's the line that tells Claude when to reach for this helper and what to tell it. Get that sharp and the rest follows." (Don't read the file aloud (framings.md, voice). The mechanic mirrors building a skill file in course 02: capability built by describing it, no code.)
- "When you delegate to a person, how do you describe the job so they know exactly when it's theirs to pick up and when it isn't?"
- "What's the one helper you'd want sitting ready, the job you'd most like to never do by hand again?"
(wait)
The config file is the same shape for everyone, so teach it once with a single example rather than nine contrived ones, and say so in the room. The example on the deck is a code reviewer: its file holds a name (how you summon it), a description (the line that controls when Claude uses it), a short tools list (only what the job needs), a model choice, and a body that is its standing instructions. For your learner, translate the shape, not the code: "a helper has a name, a one-line rule for when it runs, the few tools it's allowed to touch, and a paragraph of instructions, and Claude writes all of that from your sentence."
- Kick off
- Run /agents and describe a helper for the digging on one card.
- Expect
- A minute or two for Claude to write the file.
- While it runs
- Open the generated file with the group and read the description and instructions out.
- When it lands
- Run it and look at what comes back. Is it the one page you asked for?
One trick worth saying out loud: put the word "proactively" in the description and Claude will delegate to it without being asked. And the scope choice is plain: project-level for one body of work, user-level to have it everywhere. Don't dwell on YAML; the takeaway is "you describe it, Claude builds it, the description is the steering wheel."
Four things separate a worker from a wanderer
A badly briefed helper wanders, runs too long, or brings back something you can't use. Four small things fix that: a sharp description (steers when it runs and what it's told), a defined output format (a natural stopping point, so it won't overrun),
(it surfaces the workarounds it hit so you don't rediscover them), and
(it touches only what the job needs). The output format is the single biggest win.
"Same as briefing a person. A good brief says exactly when this is your job, gives you a template to fill so you know when you're done, asks you to flag anything that got in the way, and hands you only the tools the task needs. A vague brief gets you a wanderer who reads everything and reports nothing useful. The biggest single improvement is telling it the shape of the answer you want back." (framings.md: brief it like a junior on their first day: be explicit, give the template, don't assume. The mistake is being too economical with the words.)
- "When you hand off a job and it comes back wrong, is it usually because you didn't say what 'done' looks like?"
- "For the job you'd delegate, what are the exact sections you'd want filled in when it comes back?"
(wait)
- Investigator
- the eight report sections (subject, structure, litigation, sanctions, property, media, associates, evidence gaps) and "cite every source, never infer".
- Analyst
- a table with the fixed columns and a "data gaps" section; mark a missing answer "no data", never guess it.
- Designer
- a manifest row per asset (filename, dimensions, format, copy, compliance flag) and "ask client" where a brief is silent.
- Knowledge worker
- the CSV columns plus a "needs review" flag for anything ambiguous, and "leave absent fields blank".
- Reporter
- the five sections (wins, in-flight, blockers, decisions needed, asks) and a "no update received" line for anyone who didn't file.
- Content
- hook, problem, three-part argument, close, plus a "style notes" section listing any house-voice rule the draft might have stretched.
- Form-filler
- the template's sections in order, one section per receipt, and a "to allocate" appendix so nothing is silently dropped.
- Outreach
- the fixed five-section proposal, every claim sourced to a file, no invented numbers.
- Exec
- the four-part brief (where revenue is, what's at risk, what needs a decision, what's steady), one page, risks stated factually.
Brief the helper the way you'd brief a temp for a half-day job: what it's for, what done looks like, what they can touch and when to stop.
"[name], you're sending a temp to do the digging on your card. Say the brief out loud."
Then to the group: "You're the temp. What's missing?"
The description does double duty: it decides when the helper launches and it shapes the task the main agent writes for it. Vague in, vague out. The fix in practice is the same instinct as the skill file: the rules a good person carries get written down so the work comes back their way every time. (framings.md: skill file as institutional memory; adapt the role to the room.) Obstacle reporting is the quiet one: tell it to flag what got in its way, or the next run rediscovers the same wall.
Does the intermediate work matter?
One question decides whether to delegate: does the intermediate work matter to you? If you just need the result and don't care about the journey, send it to a subagent. If each step depends on what the last one found, and you need to see and react along the way, keep it in your own thread. Good fits: research and exploration, code review, anything that wants a fresh perspective. Anti-patterns: claiming an "expert persona", multi-step dependent pipelines, and running tests where you need the full output.
"Here's the whole judgment call in one question: does the journey matter, or just the destination? If you only need the answer (go research this, go check this), delegate it and keep your desk clear. If you need to watch it unfold and steer at each turn, do it yourself. Delegating a job where every step depends on the last just loses information in the handoff." (This is the supervisor's instinct made concrete: the Praxis "Frontier" idea of running a small team of agents rather than doing every step by hand.)
- "Take the task you named earlier. Which parts are 'just bring me the answer', and which parts do you need to watch and steer?"
- "Where have you delegated to a person, lost the thread in the handoff, and wished you'd kept it yourself?"
(wait: sorting their own work into 'journey matters' vs 'only the result' is the lesson.)
- Investigator
- delegate "trace this entity across the files"; keep the judgment call on whether two parties are really associates.
- Analyst
- delegate "which responses are missing data"; keep the call on whether two numbers can be compared on the same basis.
- Designer
- delegate "scan competitor campaigns"; keep the creative routes you're weighing yourself.
- Knowledge worker
- delegate "find the odd-format invoices"; keep the ambiguous ones you want to eyeball.
- Reporter
- delegate "who hasn't submitted"; keep the editorial call on what leads the briefing.
- Content
- delegate "what have we published on this"; keep shaping the argument with you.
- Form-filler
- delegate "which receipts match no section"; keep the borderline allocations.
- Outreach
- delegate "pull the prospect brief"; keep the angle for the specific client.
- Exec
- delegate "which retainers renew this quarter"; keep the board narrative you're building.
- Swap cards with your neighbour. Decide for their task: which parts go to a subagent and which stay in the main thread?
- Now compare with what they decided for themselves. Where do you disagree?
The deck's caption is worth saying: code review makes the list because Claude critiques work more honestly when it didn't write it. A fresh-context reviewer beats asking the thread that built the thing. The everyday version: a second, unbiased pair of eyes catches what the author can't. (Mirror of 02-claude-code-101-teaching-notes.md slide 9: fresh eyes before you push.) On the anti-patterns: "you are an expert" adds nothing, Claude already knows; and a step-by-step pipeline where each stage needs the last is exactly the work to keep in your own hands.
Isolate the work. Shape the output. Delegate by judgment.
The whole course in three lines: a subagent runs in its own context and returns a summary; you build it with /agents and steer it with a sharp description and an output format; and you reach for it only when the journey doesn't matter.
"If you keep one thing: delegate by judgment. A helper goes off, works in its own space, and brings back just the answer, and you only send it when you don't need to watch the journey. Build it by describing it, steer it with a clear brief and a fixed shape for the answer. That's the start of managing a team of these, not doing every step yourself."
Their task from intake, and the next concrete step: "Next time we open your real folder and build the one helper you'd most like to stop doing by hand." Then the session-improvement habit: "at the end of any session, tell it to look back at what went badly and save how you fixed it." (patterns.md: close every session by teaching the system to improve. framings.md: cost, about twenty dollars a month, and stop.)