Home

Create a Subagent in Claude Code

You want to compare investment opportunities, but researching multiple companies and scoring them takes hours. Think of a subagent like hiring a financial analyst who knows exactly how to use your research tools—you give them company names, and they gather reports, score each company across key metrics, and recommend the best investment. Once you learn to build subagents, you can automate any repetitive multi-step workflow in your work. This tutorial shows you how to build that analyst.

Key Concepts

What You’ll Need

Step 1: Open Your Project Folder and Start Claude Code

Your stock-report Skill lives in the same project folder you used for the Skill tutorial — reopen that folder rather than starting a new one.

Windows (PowerShell):

Mac:

Log in with your Claude subscription following the installation tutorial (Windows Mac). After logging in, you’ll see a welcome message and the Claude Code prompt.

Step 2: Verify the Stock Report Skill Exists

Before building your subagent, confirm the skill is available. Type:

List all available skills

You should see stock-report in the output. This skill researches companies and generates reports covering product news, management updates, financial performance, and analyst insights.

If you don’t see it, the skill files should be in .claude/skills/stock-report/ (project level). If the folder is missing entirely, go back and complete the Create Your First Claude Skill tutorial in this same project folder first.

Step 3: Understand Subagent vs Skill Architecture

Here’s how subagents and skills work together:

Component Purpose Example
Skill Gathers raw data about one company “Generate report for Apple: products, financials, management, analysts”
Subagent Uses skill data to accomplish a goal “Get reports for Apple and Microsoft, score both, recommend which to invest in”

Key difference:

Your stock-picker subagent will:

  1. Invoke the stock report skill for each company (2+ times)
  2. Score companies across categories (financials, growth, management, sentiment)
  3. Compare scores and recommend the best investment

Step 4: Create the Stock Picker Subagent

Ask Claude to write the subagent file for you. Copy and paste this prompt:

Create a project subagent called stock-picker in .claude/agents/:
- It takes two or more stocks
- Uses the stock-report skill to do research
- Score cards are created based on the categories of data collected
- A final recommendation is given.
Use the Sonnet model.

Claude creates the file .claude/agents/stock-picker.md. If Claude asks for permission to create the file, choose Yes.

Note: In older versions of Claude Code, typing /agents opened a menu for creating subagents. In current versions, /agents only reminds you to ask Claude, which is what we just did.

Tools: A subagent can be limited to only the tools it needs—for example, a research-only agent with just web search. If the file has no tools: line, the subagent can use all tools, which the stock-picker needs to research online and write files.

Step 5: Review What You Built (Reflection Checkpoint)

To open the file in VS Code, click File > Open File… and navigate to .claude/agents/stock-picker.md.

Or you can ask Claude to:

Show me the stock-picker subagent file.

Claude will display the subagent file located at .claude/agents/stock-picker.md. You’ll see:

There is a YAML frontmatter at the top:

---
name: stock-picker
description: Compares multiple companies for investment decisions...
skills:
  - stock-report
model: sonnet
---

This frontmatter (the section between --- markers) tells Claude Code when to use this subagent (description) and which skills to load into it from the start (skills), and which Claude model it runs on (model).

There is a System prompt below the frontmatter with your scoring methodology.

Confirm these key elements:

You can edit the file directly or ask Claude to update it.

Step 6: Test the Subagent

First quit Claude Code by pressing Ctrl+C twice, then type claude to start it again. Claude Code only notices a brand-new .claude/agents/ folder after a restart.

Now test your subagent with a real comparison. Type:

Which is a better investment: Apple or Google?

The subagent will automatically activate based on your description.

Step 7: Watch the Subagent Work

The subagent runs in the background, so you’ll see its name in a small panel below the prompt rather than every step. To watch it, type /tasks, use the arrow keys to select stock-picker, and press Enter. Behind the scenes, it will:

  1. Invoke the skill twice - Call the stock-report skill once for Apple, then for Google
  2. Gather data - Each skill call searches the web and generates a company report
  3. Score companies - Scores each category and combines them into an overall score
  4. Generate output - Creates comparison table and recommendation

This may take 2-3 minutes since web research is involved.

Notice that your main conversation doesn’t fill up with all the search results and intermediate steps—that’s the isolated context at work. The subagent does its research in its own separate workspace and only reports back what you see here.

Step 8: Review the Output

The subagent returns a detailed analysis including:

The subagent may display this in the terminal or generate a markdown file with the full report. You can edit the subagent file to customize scoring weights or output format.

Next Steps

Now that you have a working stock-picker subagent, try these extensions:

Troubleshooting

Workflow Overview

Created by Steven Ge on December 14, 2025.