Second engineer: subagent

1. What goes into the subagent file

Tommy already understands everything about the subagent: it is a separate worker with its own clean head, living in the file .claude/agents/reviewer.md. In essence, it is a second engineer, whom he is about to hire now. It shows up with fresh coffee and the right mindset — if you can set up a specialist for a role, then let’s set one up:

“Listen, okay, I get what a subagent is now. So let’s do it hands-on. How do I actually set up such a reviewer? Where is the button?”

“There is no button — there is a file, you have already seen it,” Alex replies. “Time to look inside. Inside .claude/agents/reviewer.md is the worker description. At the top is a small service block, and under it is what the worker should do in plain words:”

---
name: reviewer
description: Reviews code for bugs and rough edges. Use when someone asks for a fresh look at a finished thing.
---

# Reviewer

Read the code, find bugs, annoyances, and rough edges. Return a list of findings
with priorities. Do not fix anything yourself — just report.

“And those two lines at the top, in the frame?” Tommy peers closely.

“There are only two of them, and both are simple. name is the worker name, reviewer, and that is how you call it. description is the most important part: when to call it. Based on this description, the main agent itself understands that the task is for the reviewer and hands it over. And below, in plain words, is what the worker should do. Notice the last line of the task: ‘do not fix anything yourself — just report.’ We set up a nitpicker to look, not to fix. Let it find things and report them — and we will decide and fix them ourselves, consciously.”

“And why not let it fix things right away too?”

“Because those are two different jobs, remember? The one who found it is not necessarily the one who fixes it. The nitpicker nitpicks. How to fine-tune a worker — what it can do, what it cannot, what model it should think on — that is a separate big topic much later. Today, it is enough to define the role in words: who it is and what it does. Put this file in place — and the subagent is ready.”

2. How to check it and how to delegate

“Let’s check that the worker is there,” Alex continues. “No special commands are needed. Type one at sign in the prompt:”

@

A list drops down — and in it, among the project files, there is reviewer with its description.

“Oh, there it is.” Tommy points at the screen. “And I thought you had to register it somewhere in the settings.”

“No need. Put the file in .claude/agents/ — and a couple of seconds later the worker is available. The agent watches that folder by itself. You do not need to restart the conversation, and you do not need to click anything. And by the way, this is the most reliable way to check that your description was picked up: if the worker appears behind the at sign, then this session knows about it. If it does not appear, then something is wrong with the file — go check it.”

“And if it had not been picked up?”

“There is exactly one case,” Alex says. “If the folder .claude/agents/ did not exist at all when you started the conversation. The session does not track a new folder — it did not know about it at startup. In that case, restart while saving the conversation:”

claude --continue

flowchart LR
  F["Put the file
in .claude/agents/"] --> C{"Type @ —
is the worker listed?"}
  C -->|"yes"| OK["The worker is in place —
you can call it"]
  C -->|"no"| W{"Did you create .claude/agents/
during this session?"}
  W -->|"yes"| R["Exit and run
claude --continue"] --> C
  W -->|"no"| X["Something is wrong with the file —
go check it"] --> C

“And that is it, after that the folder is in place, you can drop in the next workers and use them right away. This is a one-time thing, for the first worker. Now for the good part. We assign it an analysis based on your brief — in plain words:”

Let reviewer analyze my Snake using REVIEW_BRIEF and figure out what to improve.

What matters here is the idea itself. You do not walk the reviewer through the steps — you do not say, “now open this file, now check the tail, now look at the controls.” You hand over a narrow task in one piece and step away: it opens the needed files on its own, runs everything on its own, and returns the findings on its own. That is what delegating means — not doing it by hand, but assigning the job and getting the result. Before, you led the AI agent by the hand through every step; now you have a worker to whom the task is handed over in full. (How that feels in practice — you will experience it when you run the nitpicker yourself from scratch.)

“Can I call it in a more… targeted way? If it does not figure it out on its own?”

“You can. Through the same at sign, directly by name:”

@reviewer check this

“So the at sign has two jobs,” Alex adds. “Type it once and see who is even on staff. Type it with a name and point at a specific one. If the name is long and you do not feel like typing it, choose it from the same drop-down list, and the agent will insert it itself. But usually it already understands the task by meaning — that is what the description is for. An explicit call is for when you want to be sure.”

3. The boss role: choose, do not implement everything blindly

“And now you are in a new role,” Alex continues. “You are the boss. The subagent produced a list of findings, but deciding what to do with them is up to you. And there is an important habit here: do not implement everything blindly. You looked at the findings, chose consciously — this one I will fix because it is a real bug, and that one I will leave alone because it is taste, and I like it as it is. A good manager does not do everything a subordinate suggests. They choose.”

flowchart LR
  T["You: a task
per the brief"] --> M["The main agent
hands it to the reviewer"] --> S["The subagent analyzes it
in its own window"]
  S --> L["List of findings"] --> B{"You’re the boss:
what about each finding?"}
  B -->|"a real bug"| Fix["I fix it"]
  B -->|"a matter of taste"| Skip["I leave it"]

“Makes sense.” Tommy nods. “I am the boss, not the executor of its whims.”

“Well, there you go, you have said it yourself. And one quiet nuance for the future,” Alex says lightly, as if in passing. “The subagent has its own attention window. It does not know what was said in our main conversation. Sometimes because of that, it may miss something. For now, just remember that. And what to do with that like an adult — not trust the assistant blindly, check its conclusions — that is a separate big topic much later. Today, just remember that its window is its own.”

4. Bonus: you can give a task by voice

“Since today is about convenience,” Alex adds almost casually, “I have one trick for you. You can speak any text to the agent instead of typing it. There are two ways: the speech recognizer built into Claude and an external utility.”

If you want to use the built-in method, you first need to enable voice mode. The command is:

/voice hold

“hold means the ‘press and hold — speak — release’ mode. Hold down the space key, speak the task out loud, release it — the text appears automatically, and the agent receives plain text. If you type slowly or the task is long, this is a real superpower.”

Tommy perks up — he does not type very fast.

“So, we will be able to talk by voice now?”

“Do not get carried away,” Alex says gently. “This is just a convenient input, not a separate kind of magic. The text path is always still there — if you want, type as before. Voice only replaces the keyboard with your mouth, that is all. I will still write in text. Voice input — just a nice bonus. And keep in mind: the built-in voice feature is tied to a Claude subscription — it will not work on our course access. So the working option for us is the second one.”

“All right, got it. And what is the second way?”

“The second way is to install a free utility called Handy. Unlike Claude, it gives you voice input for any program on the computer. It works completely free, even without the internet.”

“The second option seems better somehow,” Tommy thinks out loud. “It works for any program on the computer, without the internet. Definitely free? And how do I install it?”

“Just ask the AI agent to install it for you. Actually, it should have done that back at the very beginning, when you were installing Claude Code on day one. But if you do not have it, ask the AI to install it. The command may look something like this:”

Install the Handy app for local voice input: https://github.com/cjpais/Handy

“Wow, it works.” Tommy is already dictating something. “In short, I did everything: set up the role file, checked with the at sign that it was there, then called it with the same sign, and it analyzed everything itself and brought back the findings. And I choose what to take. I do not call a function — I delegate the work.”