Lesson 5.6 — Subagents & Your First Swarm

Introduction to AI · Module 5: AI Agents · About 90 min · Windows PC, PowerShell 5, Claude Code (Max)

Goal: build a 3-agent team: researcher, writer and checker. They produce a one-page brief on a topic you care about, with the main Claude acting as the boss (orchestrator).

Before you start

• cd $HOME\agent-night
• Choose a topic (e.g. "best ways to cut my home power bill in Brisbane"):
• Optional: the fetch MCP server from 5.2 helps the researcher

Step 1 · Create the team folder (⏱ 0:00–0:05)

mkdir swarm -Force | Out-Null
cd swarm
mkdir .claude\agents -Force | Out-Null

• Folder ready

Step 2 · Define the 3 subagents (⏱ 0:05–0:25)

Paste the whole block. It writes 3 agent files, without a BOM:

$dir = "$HOME\agent-night\swarm\.claude\agents"
[IO.File]::WriteAllText("$dir\researcher.md", @'
---
name: researcher
description: Finds facts on a topic from the web. Use for any research step.
tools: WebSearch, WebFetch, Read, Write
---
Research the topic you are given. Write work\notes.md with 8-12 facts.
Each fact gets a source URL. No opinions. Mark anything uncertain with (?).
'@)
[IO.File]::WriteAllText("$dir\writer.md", @'
---
name: writer
description: Turns research notes into a one-page brief. Use after research.
tools: Read, Write
---
Read work\notes.md. Write brief.md: a title, a 3-line summary, 5 actions
(each with a cost or saving if known), and a Sources list. Max 1 page.
Plain Australian English. Use only facts from the notes.
'@)
[IO.File]::WriteAllText("$dir\checker.md", @'
---
name: checker
description: Checks a brief against the notes. Use after writing.
tools: Read, Write
---
Compare brief.md with work\notes.md. List every claim in brief.md that is
not supported by the notes, any missing sources, and anything over 1 page.
Write work\check.md ending with the line VERDICT: OK or VERDICT: FIX.
'@)
dir .claude\agents

You should see researcher.md, writer.md and checker.md.

• 3 agent files

Step 3 · Check Claude sees them (⏱ 0:25–0:30)

claude

Type /agents. You should see researcher, writer and checker listed under project agents. Press Esc.

• Team visible

Step 4 · Run the swarm (⏱ 0:30–1:05)

Still in Claude, type (put your topic in):

You are the orchestrator. Topic: <your topic>.
1) Use the researcher subagent to write work\notes.md.
2) Use the writer subagent to write brief.md.
3) Use the checker subagent. If VERDICT: FIX, send the writer back with
   work\check.md, then re-check. Max 2 rounds.
4) Finish with a log: which agent did what, in order.

Approve tool use as it goes. Watch: each subagent starts fresh and reports back to the boss.

• Orchestrator printed its log

Step 5 · Inspect the hand-offs (⏱ 1:05–1:20)

Leave Claude: **type /exit and press Enter. Wait until you see PS C:\...> before the next command.** Then in PowerShell:

Get-Content work\notes.md | Select-Object -First 10
Get-Content work\check.md
notepad brief.md

You should see notes with URLs, a check ending in VERDICT: OK (or a fix round), and a 1-page brief.

Fill in:

• Table filled in

Step 6 · Reflect (⏱ 1:20–1:30)

Why was a separate checker useful (or not)?

✅ Pass check

• brief.md exists, 1 page, with sources
• work\check.md exists and ends with a VERDICT
• You can show which agent did what (the orchestrator log plus the table)
• Told Skills Coach so 5.6 gets marked done

Troubleshooting