Since Week 1 you've split work across role-chats: one codes, one reviews, one designs. A subagent is that idea, automated — the role becomes a file, and the main agent delegates to it by itself.
A separate "worker" with its own system prompt, its own context window, and its own set of allowed tools. The main agent hands it a narrow task; it works in isolation and returns only the result. The noise — file reads, searches, intermediate steps — stays inside. You've already seen this happen: in plan mode (Week 2), the exploration step ran as a delegated task with its own model.
Markdown with YAML frontmatter, one file per role:
.claude/agents/ in the project (shared via repo; wins on name collision), or ~/.claude/agents/ (personal).name, description (when to delegate), optionally tools and model. The body is the subagent's system prompt./agents command, which walks you through creation step by step.A reviewer, ready to use — .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Use after completing a feature or before opening a PR. Reviews the diff and returns issues found.
tools: Read, Grep, Glob, Bash
model: opus
---
You are a strict code reviewer for this project.
Review the current diff against CLAUDE.md conventions.
For each issue: file, line, what's wrong, how to fix.
Check: shared code touched? secrets in the diff? tests testing real behavior?
You do NOT edit files — you report.
Two details that carry the safety model of this whole track:
tools is a boundary (Week 2's idea, enforced): this reviewer has no edit access — it literally cannot "fix" things on its own. If tools is omitted, the subagent inherits everything; restrict deliberately.description is the trigger. The main agent decides to delegate by reading it. Write it as "Use when… / Use after…" — vague descriptions mean the subagent never fires, or fires at the wrong time.Both keep context clean by delegating to separate workers. Manual role-chats — when you want to watch the process and hold long sessions. Subagents — when the role repeats and you want it to fire without you: review before every PR, exploration in every plan. Most real setups use both.
📸 Screenshot needed: a delegation visible in a session — the main agent handing work to a named subagent (your plan-mode screenshots from Week 2 already show a delegated exploration task — crop one). Second frame: the
/agentsUI in the CLI.
The HackYourFuture curriculum is licensed under CC BY-NC-SA 4.0 *https://hackyourfuture.net/*
Built with ❤️ by the HackYourFuture community · Thank you, contributors
Found a mistake or have a suggestion? Let us know in the feedback form.