Subagents

What are subagents?

Subagents are specialized Claude assistants that handle specific tasks. Each one runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns just the summary — keeping your main conversation clean.

For marketing work, think of them as named specialists you can summon over and over: a copywriter that always writes in your brand voice, a researcher that always investigates the same way, a critic that always pushes back on weak positioning.

Subagents vs Agent Teams — quick reminder

For this guide, we'll create reusable marketing specialists you can call on across projects.

Step 1 — Open VS Code in your project folder

Open VS Code, then File → Open Folder, and select your project. For this exercise, create a new folder for the IE-Nergy work:

~/Documents/ienergy-marketing

Step 2 — Open the integrated terminal

Use the menu Terminal → New Terminal, or press Ctrl+` (backtick) on Windows/Linux or Cmd+` on Mac. The terminal opens at the bottom of VS Code.

Step 3 — Verify Claude Code is installed

In the terminal:

claude --version

You should see 2.1.32 or later. If not, update:

npm install -g @anthropic-ai/claude-code

Subagents are markdown files with YAML frontmatter. Where you save them determines who can use them:

For class, use project-level (.claude/agents/) so each student's work stays self-contained and can be checked into git if needed.

The simplest method is the built-in /agents command, which walks you through creation interactively.

Step 1 — Launch Claude Code

In the VS Code terminal:

claude

Step 2 — Open the agents interface

Once Claude Code is running, type:

/agents

This opens a tabbed interface for managing subagents.

Step 3 — Create a new agent

• Switch to the Library tab
• Select Create new agent
• Choose Project (saves to .claude/agents/ in your current folder)

Step 4 — Generate with Claude

Select Generate with Claude. When prompted, describe the subagent you want. For our IE-Nergy work, paste:

A senior brand strategist subagent for challenger consumer brands. It
should develop sharp positioning, key messages, and channel strategy.
It must be skeptical of generic claims like "premium" or "natural" and
always push for ownable, defensible angles. It should explicitly state
what NOT to say and ground every recommendation in audience insight.

Claude generates the identifier, description, and full system prompt for you.

Step 5 — Select tools

For a strategist that should think and write but not execute code, deselect everything except Read-only tools and Write (so it can save its strategy.md output).

Step 6 — Select model

Pick Sonnet for a good balance of capability and speed. For very simple subagents, Haiku is faster and cheaper. For deep reasoning tasks, Opus.

Step 7 — Choose a color

Pick a color so you can spot the strategist easily in the UI when it's running. Blue or purple work well.

Step 8 — Save

Press s or Enter to save. The file is created at:

.claude/agents/strategist.md

You'll see it appear in your VS Code file tree immediately.

Step 9 — Try it out

Back in Claude Code, ask:

Use the strategist subagent to develop positioning for IE-Nergy, a new
energy drink targeting university students who want clean focus, not
aggressive stimulation. Save the output to strategy.md.

Claude delegates to your subagent, which produces a strategy document and saves it.

Once you understand the structure, creating subagents directly in VS Code is faster. Each subagent is a markdown file with two parts: YAML frontmatter (the configuration) and a markdown body (the system prompt).

Step 1 — Create the agents folder

In the VS Code terminal, or right-click in the file tree:

mkdir -p .claude/agents

Step 2 — Create a copywriter subagent

In VS Code, create a new file: .claude/agents/copywriter.md

Paste this:

---
name: copywriter
description: Direct-response copywriter for digitally-native consumer brands aimed at Gen Z and young Millennials. Use when drafting Instagram, TikTok, email, or search ad copy.
tools: Read, Write
model: sonnet
color: orange
---

You are a direct-response copywriter who has written launch campaigns
for digitally-native consumer brands aimed at Gen Z and young
Millennials.

You write in a conversational, specific voice — never corporate, never
brand-speak. You write differently for Instagram vs TikTok vs email vs
search. Each channel has its own native rhythm and format.

You hate buzzwords. Words you refuse to use: "elevate," "unlock your
potential," "fuel your journey," "level up," "crush it," "game-changer,"
"curated experience."

When invoked:
1. Ask which channel(s) the copy is for if not specified
2. Ask for the positioning and key messages — never write blind
3. Draft tight, specific copy that respects each channel's format
4. Include character counts and format constraints (e.g., 30-char
   headlines for Google Ads, 125-word max for Instagram captions)
5. Provide 2-3 variations when there's room for stylistic choice

For TikTok scripts, include shot direction and on-screen text cues, not
just dialogue.

Save the file.

Step 3 — Create a researcher subagent

Create .claude/agents/researcher.md:

---
name: researcher
description: Competitive intelligence analyst with marketing background. Use when investigating competitors, identifying positioning gaps, or finding category whitespace.
tools: Read, Write, WebFetch, WebSearch
model: sonnet
color: green
---

You are a competitive intelligence analyst with a marketing background.

You investigate not just what competitors say, but what they DON'T say —
looking for whitespace and positioning gaps the brand could credibly
own.

You report findings as actionable insight, not feature comparison
tables. You're comfortable making confident judgments from limited data.

When invoked:
1. Identify 3-5 most relevant competitors (direct + adjacent)
2. For each, summarize their core positioning in ONE sentence
3. Identify 2-3 positioning gaps the brand could own
4. Flag at least one risk or counter-argument for each gap
5. Save findings to research.md

Focus on insight over information. A short, sharp report beats a long
exhaustive one.

Step 4 — Restart Claude Code

Subagents are loaded at session start. Exit (/exit) and relaunch:

claude

(Alternatively, type /agents and your new ones will be picked up.)

Step 5 — Verify they're registered

In Claude Code:

/agents

You should see strategist, copywriter, and researcher in the Library tab under "Project."

You have three ways to call a subagent.

Method 1 — Natural language

Just name the subagent in your prompt:

Use the researcher subagent to investigate Red Bull, Monster, and
Celsius. Then use the strategist subagent to develop IE-Nergy's
positioning based on the research. Finally use the copywriter to
draft a TikTok script and an Instagram caption.

Claude reads your request and invokes each subagent in turn. This is the most natural way to work.

Method 2 — @-mention (more precise)

Type @ and pick from the autocomplete:

@researcher (agent) investigate the energy drink category for me

This guarantees Claude invokes that specific subagent.

Method 3 — Run an entire session as a subagent

Launch Claude Code with a subagent as the main session:

claude --agent strategist

The whole session takes on the strategist's persona, tools, and model. Useful when you want to spend a focused session entirely in one role.

Here's an end-to-end example of how subagents work in practice.

Step 1 — Set up the project

In VS Code terminal:

mkdir ~/Documents/ienergy-marketing
cd ~/Documents/ienergy-marketing

Open this folder in VS Code (File → Open Folder).

Step 2 — Add the brief

Create brief.md in VS Code with the IE-Nergy brief (product details, audience, channels, etc. — same as in your Agent Teams exercise).

Step 3 — Create your three subagents

Either via /agents command or by creating the three markdown files manually as shown in Part 4.

Step 4 — Run the workflow

In Claude Code, paste:

Read brief.md. Then:

1. Use the researcher subagent to analyze 3 competitors (Red Bull,
   Monster, Celsius) and identify positioning gaps. Save to
   research.md.

2. Once the researcher is done, use the strategist subagent to
   develop IE-Nergy's positioning, key messages, channel mix, and
   explicit "what we won't say." Use research.md as input. Save to
   strategy.md.

3. Once the strategist is done, use the copywriter subagent to draft
   one Instagram caption, one TikTok script, one email, and one
   Google Search ad. Use strategy.md as input. Save to copy.md.

4. After all three subagents finish, produce a final
   campaign-summary.md tying everything together with your
   recommendation.

Claude calls each subagent in sequence. Each one works in its own context window, then returns a summary to the main conversation. The full deliverables get saved to disk where you can open them in VS Code tabs.

Step 5 — Review in VS Code

When the workflow finishes, you'll have four files in your file tree:

• research.md
• strategy.md
copy.md
• campaign-summary.md

Open each in VS Code tabs to review side-by-side. This is where the value is — critique the output, iterate, push the subagents to do better.

• Make your subagents specific. A "writer" subagent is useless. A "TikTok script writer who specializes in unboxing-style demos for beauty brands" is genuinely useful. Specificity makes them better at their job.
• Tell them what NOT to do. The most useful line in the copywriter file above is the buzzword blocklist. Constraints sharpen output for AI just as much as for humans.
• Use the description field carefully. Claude decides when to delegate based on the description field. Phrases like "use proactively" or "use when drafting copy" prompt Claude to delegate automatically.
• Check subagents into git. When you save them to .claude/agents/ in a project, they go into version control. Your team (or classmates) get the same specialists when they pull the repo.
• Reuse personal subagents across projects. When you find a subagent definition you love, save it to ~/.claude/agents/ instead of .claude/agents/. It'll be available in every project on your machine.
• Iterate on the prompt. Open the .md file in VS Code, edit the system prompt, save, restart Claude Code. The fastest way to improve a subagent is to refine its definition based on the actual output it produces.

Create folder for project subagents:

mkdir -p .claude/agents

Create one interactively:

claude
/agents
→ Library → Create new agent → Project

List all available subagents:

/agents

Invoke a subagent:

Use the researcher subagent to...
@researcher (agent) investigate...
claude --agent strategist (whole session)

Subagent file location:

.claude/agents/<name>.md   (project)
~/.claude/agents/<name>.md (personal, all projects)

Reload after editing a file:

/exit, then claude