This lesson is being recorded
Every video of this course is being uploaded to my YouTube channel. Subscribe so you do not miss it.
Bruno Ashford @brunoashfordSubscribeModule 7 · Lesson 7.2 · 12 min
Creating Your First Subagent
Build a specialist (analyst, writer or reviewer) with the /agents command and understand every line of its file.
Use ← → to move. The marker highlights text and the pencil draws on the slide; navigation locks while you annotate. Undo removes the last mark, Esc exits.
1Start the guided creator
Run /agents and choose to create a new agent. Pick project level so it lives with this business. The easiest route is to let Claude generate a first draft from your description, then edit it.
/agents2Describe the role like a job post
When asked, describe the role in plain English: what it does, what it receives, what it returns, and what it must never do. The description field matters most, because Claude uses it to decide when to hand work to this agent.
A data analyst for my business. It reads CSV and spreadsheet exports from the data/ folder, calculates revenue, number of orders, average order value, repeat customer rate and month over month change, and returns a short summary with a table. It never edits or deletes source files. It writes its reports only to reports/. Use it whenever I ask about sales numbers, trends or performance.3Choose tools with least privilege
An analyst needs to read files, search them and write a report. It does not need web access or connectors that can send messages. In the file header this becomes a comma-separated tools line. If you leave tools out, the subagent inherits every tool the main session has, which is rarely what you want.
4Read the file it created
Open .claude/agents/data-analyst.md. You will see the header between two lines of three dashes, with name, description, tools and optionally model (sonnet, opus, haiku, or inherit to use the main conversation's model), followed by the job description. Edit the body in plain English whenever the role changes. The materials for this module include four complete examples.
5Call it by name
Claude may delegate automatically based on the description, but at first call it explicitly. You can type @ and pick the agent from the list, or simply name it in your request.
Use the data-analyst subagent to analyse data/orders-2026-09.csv against data/orders-2026-08.csv and tell me the three numbers that changed the most and why they might have changed.6Tune after three runs
Run it on three real tasks. Each time it does something you did not want, add one clear sentence to its instructions. After three rounds most subagents are reliable, and the file becomes a documented role anyone on your team can read.
Writing a subagent is closer to writing a job description than writing code. If you have ever hired someone, you already have the skill. The difference is that this hire reads the job description every single time, word for word.
In this lesson you create a data analyst subagent step by step. It reads your sales exports, calculates the numbers you care about, and never edits your source files.
Key points
- A subagent file is a job description with a short header.
- The description decides when Claude hands work to it.
- Give only the tools the role needs; omitting tools means it inherits all of them.
- Tune with one sentence per mistake over three runs.
Avoid
- Writing a vague description like 'helps with stuff', so it is never used or used for everything.
- Leaving tools out and giving an analyst the power to send emails.
- Editing a subagent after one bad run instead of watching for a pattern.
A skincare e-commerce store exports orders from Shopify every Monday. The owner created a data-analyst subagent limited to reading the data/ folder and writing to reports/. After two rounds of tuning it produced the same one-page Monday summary every week: revenue, average order value, repeat rate and top five products, with a flag when any number moved more than 15 percent. The owner reads it with her coffee instead of building a pivot table for an hour.