Claude Code Subagents Tutorial: Build an AI Team
Follow the Developers Digest demo frame by frame: create subagents with the /agents wizard, give each its own tools and system prompt, then watch a research agent and a front-end agent build a landing page together.
TL;DR
- Type /agents in Claude Code to open the agent panel and create your first subagent in about a minute.
- Each subagent is a single markdown file in .claude/agents/ with a name, a description, a tool list, and a system prompt.
- Generate agents with Claude, then scope their tool access — including MCP servers like Firecrawl or Context7 — and pick a terminal color.
- In the demo, a web-research subagent and a Next.js front-end subagent research AI news and build a SaaS landing page end to end.
Claude Code NEW Sub Agents in 7 Minutes
Video walkthrough:Developers Digest7:10
Create subagents — Claude Code official docs
Official docs ·:Anthropic
Screenshots come from the Developers Digest walkthrough; terminology and file conventions were cross-checked against Anthropic's official sub-agents documentation.
All screenshots remain the property of Developers Digest and are used here to illustrate the tutorial; timestamps link back to the original video.
Create Claude Code subagents, step by step
Part 1 · Create your first subagent with /agents
- 1
Open the agents panel with /agents
Inside a Claude Code session, type /agents and pick Create new agent. The panel lists every subagent you have plus the built-in general-purpose agent that is always available.
One slash command is all it takes to reach the agent manager.Watch at 0:30 - 2
Choose project or personal scope
Step 1 asks where the agent should live: Project (.claude/agents/) keeps it inside the repository, while Personal (~/.claude/agents/) makes it available in every project on your machine.
Project agents can be committed to the repo; personal agents follow you everywhere.Watch at 0:46 - 3
Let Claude generate the agent
Step 2 offers Generate with Claude (recommended) or Manual configuration. In the video a front-end specialist is requested — an expert in Next.js, Tailwind, and ShadCN/UI — and Claude drafts the whole configuration.
Describe the role once and Claude writes the file for you.Watch at 1:05 - 4
Scope the tool access
Step 4 groups everything the agent may touch: All tools, Read-only tools, Edit tools, Execution tools, and MCP & Other tools. Toggle individual tools off, or hand the agent everything like the demo does.
A front-end agent can keep all tools; a backend agent might only get database and log access.Watch at 1:36 - 5
Give it a terminal color
Pick a background color from the palette — Red, Blue, Green, Orange, Yellow, Purple, Pink, Cyan, or Automatic — and the preview shows how the agent's name chip will look in the conversation.
Colors make it obvious which specialist is running at a glance.Watch at 1:48 - 6
Review the generated prompt and save
The confirm screen shows the description Claude will use to decide when to delegate, the full system prompt, and warnings — the demo's description is flagged as over 400 characters. Press Enter to save.
You can edit any field later; the file is plain markdown.Watch at 2:15
Part 2 · Agent files and a second specialist
- 7
Find the markdown file in .claude/agents
Every subagent lives in one markdown file. The demo opens the project in Finder and shows the hidden .claude/agents folder with nextjs-tailwind-shadcn-engineer.md inside — portable enough to commit to the repo.
The folder appears once your first agent is saved.Watch at 3:10 - 8
Add a web-research specialist
Repeat the flow for a second agent. This time pick only the MCP tools it needs: the Firecrawl server's scrape, map, and search — the counter reads 3 of 25 tools selected.
Narrow tool lists keep each agent focused and predictable.Watch at 3:36 - 9
Check the frontmatter before saving
The confirm screen lists Name: web-research-specialist, Location: .claude/agents/web-research-specialist.md, the three mcp__mcp-server-firecrawl__ tools, the description, and the system prompt.
Claude writes the frontmatter and body; you can tune both anytime.Watch at 3:42
Part 3 · Delegate a live research build
- 10
Delegate a real build
Ask for a SaaS landing page with a pricing table and an FAQ, plus a hero that researches the top five AI news stories from July 2025 — and tell Claude to research the web before writing any code.
One prompt now fans out across the team you just built.Watch at 4:26 - 11
Watch Claude orchestrate the team
Claude breaks the request into a multi-step plan, decides to run the web-research-specialist agent first, then hands the build to the nextjs-tailwind-shadcn-engineer agent, and tracks it all in a todo list.
Descriptions in each frontmatter tell Claude when to delegate.Watch at 4:28 - 12
Collect the research results
The web-research-specialist finishes after 10 tool uses and 22.5k tokens in about two minutes, and Claude Code strikes the research item off the todo list before moving on.
Fresh facts flow straight into the main conversation as context.Watch at 4:38
Part 4 · The build phase and the result
- 13
Let the front-end agent build
The nextjs-tailwind-shadcn-engineer agent takes over, writing app and component files, configuration, and kicking off npm run dev while the main conversation keeps a marinating status.
The heavy file editing happens in the subagent's own context.Watch at 4:45 - 14
Review the finished site
The result is a Developer's Digest landing page: a hero built from the five researched AI stories, a three-tier pricing table, a working FAQ accordion, and dark mode — exactly what was delegated.
Specialists built it; your main conversation stayed focused.Watch at 6:12
One giant system prompt vs a subagent team
| Capability | One giant system prompt | Subagent team |
|---|---|---|
| Context | One conversation accumulates everything and drifts off topic. | Each subagent works in its own clean context window. |
| Instructions | Every rule has to be squeezed into a single prompt. | Each agent gets a focused system prompt you can grow over time. |
| Tools | All tools stay available all the time. | Per-agent allowlists, including MCP servers like Firecrawl or Context7. |
| Reuse | Copy-paste instructions between projects by hand. | Markdown files you commit to the repo or install globally. |