TL;DR — Building AI agent teams with Claude means defining agents as markdown files, running them via CLI, and coordinating through file-based memory. Start with a 3-agent pipeline (researcher, writer, editor), get it working reliably, then expand to multiple domain-aligned squads.
Why Build Agent Teams?
Single AI agents are powerful. Claude Code can read your entire codebase, run commands, and complete complex tasks autonomously. So why build teams?
Because real work requires specialization.
A single agent handling research, writing, editing, and publishing makes the same tradeoffs a single human would: context switching, conflicting priorities, and generalist-level output across all tasks.
Agent teams solve this by mirroring how effective human teams work:
- Clear roles and responsibilities
- Shared context and memory
- Parallel execution when possible
- Quality gates between stages
This guide walks through building your first agent team with Claude, from architecture decisions to production deployment.
Prerequisites
Before starting, you need:
- Claude Code CLI installed (
npm install -g @anthropic/claude-code) - Basic familiarity with Claude Code commands
- A project where you want to deploy agents
If you’re new to Claude Code, start with our Claude Code Tutorial first.
Key Takeaway — Single agents hit the same tradeoffs as single humans: context switching, conflicting priorities, and generalist-level output. Teams solve this through specialization, shared memory, and parallel execution.
Choosing a Team Architecture
Before writing any agent definitions, you need to decide how your agents will coordinate. The right architecture depends on your workflow shape, and picking wrong means rework later.
Keep using a single agent when tasks complete in one session, context fits comfortably in one window, you’re the only person running agents, or speed matters more than thoroughness. There is no reason to add coordination overhead if one agent handles the job well.
Switch to teams when tasks span multiple domains (code + docs + tests), context overflows single agent capacity, different tasks need different expertise levels, or you need audit trails for who did what.
Three patterns dominate production agent teams. Pipeline (sequential) chains agents one after another — researcher, then writer, then editor — and works best for content production, code review, and multi-stage processing. Hub-and-spoke (delegated) puts a lead agent in charge of dispatching work to specialists, which suits complex tasks that need a coordinating intelligence to decide what to do next. Squad (domain-aligned) groups agents by business function — a marketing squad with an SEO writer, social manager, and analyst, separate from an engineering squad with a code reviewer, test writer, and debugger — and works best for ongoing operations across multiple domains.
For this tutorial, we will build a content production pipeline, then expand to a full squad.
Building Your First Pipeline
Let’s build a 3-agent pipeline for content production: a researcher gathers information on a topic, a writer creates the content, and an editor reviews and improves quality.
Start with the directory structure:
mkdir -p .agents/squads/content
mkdir -p .agents/memory/content
mkdir -p .agents/outputsDefining the Researcher Agent
Create .agents/squads/content/researcher.md:
---
name: researcher
squad: content
model: claude-sonnet-4
tools:
- web_search
- web_fetch
- write_file
---
# Research Agent
## Purpose
Gather comprehensive information on a given topic to support content creation.
## Instructions
When given a topic:
1. **Understand the intent**
- What type of content will be created? (blog, guide, comparison)
- Who is the target audience?
- What search intent should it satisfy?
2. **Research systematically**
- Search for the topic + "guide" / "tutorial" / "best practices"
- Find authoritative sources (official docs, respected publications)
- Identify what top-ranking content covers
- Note gaps in existing content
3. **Compile findings**
- Key facts and statistics (with sources)
- Common questions people ask (People Also Ask)
- Competitor content structure analysis
- Expert quotes or perspectives
4. **Output format**
Save research to `.agents/outputs/research-{topic-slug}.md`:
```markdown
# Research: {Topic}
## Key Facts
- Fact 1 (Source: URL)
- Fact 2 (Source: URL)
## Common Questions
- Question 1
- Question 2
## Content Gap Analysis
What existing content misses...
## Recommended Structure
Based on top performers, suggest H2s...
## Sources
- [Source 1](url)
- [Source 2](url)Quality Standards
- Minimum 5 unique sources
- All facts must have citations
- Identify at least 3 content gaps
- Complete in under 10 minutes
### Defining the Writer Agent
Create `.agents/squads/content/writer.md`:
```markdown
---
name: writer
squad: content
model: claude-sonnet-4
tools:
- read_file
- write_file
- web_search
---
# Content Writer Agent
## Purpose
Create high-quality, SEO-optimized content based on research briefs.
## Instructions
When assigned a topic:
1. **Read the research brief**
- Load `.agents/outputs/research-{topic-slug}.md`
- Understand key facts, questions, and recommended structure
- Note the target audience and search intent
2. **Plan the content**
- Outline H2 sections based on research recommendations
- Identify where to place key facts and statistics
- Plan internal links to related content
3. **Write the draft**
- Hook: Start with a compelling first paragraph
- Structure: Use H2s and H3s for scannability
- Depth: Each section should provide real value
- Voice: Professional but approachable
- Length: Minimum 1500 words for pillar content
4. **SEO optimization**
- Include target keyword in title, first paragraph, H2s
- Add FAQ section based on "Common Questions" from research
- Use semantic keywords naturally throughout
- Write meta description (155 characters max)
5. **Output format**
Save draft to `.agents/outputs/draft-{topic-slug}.md`:
```markdown
---
title: "Article Title"
description: "Meta description here"
keywords: ["keyword1", "keyword2"]
---
# Article Title
[Content here...]Quality Standards
- Minimum 1500 words
- At least 5 H2 sections
- Include 3+ internal links
- All statistics cited with sources
- FAQ section with 3-5 questions
### Defining the Editor Agent
Create `.agents/squads/content/editor.md`:
```markdown
---
name: editor
squad: content
model: claude-opus-4
tools:
- read_file
- write_file
---
# Editor Agent
## Purpose
Review and improve content drafts for quality, accuracy, and impact.
## Instructions
When assigned a draft:
1. **Load the draft and research**
- Read `.agents/outputs/draft-{topic-slug}.md`
- Read `.agents/outputs/research-{topic-slug}.md`
2. **Structural review**
- Does the opening hook capture attention?
- Is the structure logical and scannable?
- Does each section deliver on its promise?
- Is the conclusion actionable?
3. **Quality review**
- Check all facts against research sources
- Identify unsupported claims
- Flag any content that feels thin
- Ensure consistent voice throughout
4. **SEO review**
- Is the target keyword used naturally?
- Are H2s optimized for featured snippets?
- Does FAQ section match search questions?
- Is meta description compelling?
5. **Improvement passes**
- Strengthen weak sections with more depth
- Add examples where concepts are abstract
- Tighten verbose passages
- Ensure smooth transitions between sections
6. **Output**
- Save final version to `.agents/outputs/final-{topic-slug}.md`
- Save edit notes to `.agents/outputs/edit-notes-{topic-slug}.md`
## Edit Notes Format
```markdown
# Edit Notes: {Topic}
## Changes Made
- [Change description]
## Quality Assessment
- Readability: X/10
- SEO Optimization: X/10
- Depth: X/10
- Accuracy: X/10
## Recommendations
- [Any follow-up needed]Quality Standards
- No unverified claims in final output
- Readability score must be 7+
- All sections must be substantive (100+ words)
### The Squad Definition and Memory
With all three agents defined, tie them together with a squad definition. Create `.agents/squads/content/SQUAD.md`:
```markdown
---
name: content
description: Content production pipeline
lead: editor
---
# Content Squad
## Mission
Produce high-quality, SEO-optimized content that drives organic traffic and demonstrates expertise.
## Agents
- **researcher**: Gathers information and identifies content opportunities
- **writer**: Creates initial drafts from research briefs
- **editor**: Reviews and improves content quality
## Workflow
1. Researcher receives topic assignment
2. Researcher outputs research brief
3. Writer creates draft from research
4. Editor reviews and finalizes
## Memory
- `.agents/memory/content/state.md`: Current priorities and active work
- `.agents/memory/content/learnings.md`: What works for SEO/engagement
## Outputs
All outputs go to `.agents/outputs/` and are moved to final destination after human approval.Then initialize the squad’s state file at .agents/memory/content/state.md:
# Content Squad State
## Current Priority
Building initial content library targeting comparison and tutorial keywords.
## Active Work
None currently assigned.
## Completed
- (none yet)
## Performance Notes
- (accumulate learnings here)Running the Pipeline
With everything defined, execute agents in sequence:
# Step 1: Research
claude --prompt "You are the researcher agent. Read .agents/squads/content/researcher.md for your instructions. Research the topic: 'AI agent orchestration patterns'"
# Step 2: Write
claude --prompt "You are the writer agent. Read .agents/squads/content/writer.md for your instructions. Write content for topic: 'AI agent orchestration patterns' using the research brief."
# Step 3: Edit
claude --prompt "You are the editor agent. Read .agents/squads/content/editor.md for your instructions. Edit the draft for: 'AI agent orchestration patterns'"Or wrap it in an orchestration script:
#!/bin/bash
# run-content-pipeline.sh
TOPIC=$1
SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
echo "Starting content pipeline for: $TOPIC"
echo "Step 1: Research..."
claude --prompt "You are the researcher agent. Read .agents/squads/content/researcher.md. Research: '$TOPIC'"
echo "Step 2: Writing..."
claude --prompt "You are the writer agent. Read .agents/squads/content/writer.md. Write about: '$TOPIC'"
echo "Step 3: Editing..."
claude --prompt "You are the editor agent. Read .agents/squads/content/editor.md. Edit draft for: '$TOPIC'"
echo "Pipeline complete. Check .agents/outputs/"Parallel Execution and Sub-Agents
The pipeline above runs sequentially, which is correct when each stage depends on the previous one. But many real workflows have independent tasks that can run simultaneously.
When you need multiple research threads — say, comparing three competing frameworks — spawn them in parallel:
#!/bin/bash
# parallel-research.sh
# Run three research tasks simultaneously
claude --prompt "Research: CrewAI framework" &
claude --prompt "Research: LangGraph framework" &
claude --prompt "Research: AutoGen framework" &
wait
echo "All research complete"Claude Code also natively supports spawning sub-agents. You can configure this in a CLAUDE.md so the lead agent knows when to delegate:
# Project Configuration
## Agent Spawning
When facing complex tasks, spawn specialized sub-agents:
- For research tasks: spawn a research-focused agent
- For code tasks: spawn a code-focused agent
- For review tasks: spawn a review-focused agent
Sub-agents inherit project context but have isolated execution.This matters most in hub-and-spoke architectures where the lead agent needs to decide at runtime whether to handle work itself or delegate to a specialist.
Our Data — Three agents working in parallel finish in the time one would take to complete a single task. The fan-out-then-converge pattern (independent research threads feeding a synthesis agent) is the highest-leverage parallelization opportunity.
Memory and Learning
Agents without memory repeat the same mistakes. The simplest effective approach is file-based memory — agents read a learnings file before starting work and update it after finishing.
Update squad memory after each run. In your editor agent or orchestration script, include instructions to move completed items from “Active Work” to “Completed” in .agents/memory/content/state.md and note any learnings in “Performance Notes”.
Create a dedicated learnings file at .agents/memory/content/learnings.md:
# Content Squad Learnings
## What Works
- Comparison posts ("X vs Y") get 3x more organic traffic
- FAQ sections improve featured snippet chances
- Code examples increase time on page
## What Doesn't
- Generic introductions hurt engagement
- Walls of text without headers get skipped
- Missing internal links reduce session depth
## Process Improvements
- Research phase should include "People Also Ask" analysis
- Writer should draft FAQ before main content
- Editor should verify all code examples run
## Updated: 2026-01-27Then add a “Before Starting” section to each agent’s instructions telling them to read .agents/memory/content/learnings.md, apply relevant learnings to their approach, and add any new learnings they discover after completing their work.
Over time, the learnings file becomes institutional knowledge. Agents that shipped 50 articles know things that a fresh agent does not — which content structures drive engagement, which SEO patterns actually work, which mistakes to avoid. This is the compounding advantage of agent teams over one-off prompts.
Scheduled Execution
For ongoing content operations, schedule agents to run automatically rather than triggering them manually each time.
If using squads-cli, add a schedule directly to agent frontmatter:
---
name: content-analyst
squad: content
trigger: scheduled
schedule: "0 9 * * 1" # Every Monday at 9am
---For manual scheduling, a cron entry works:
# Run content pipeline every Monday
0 9 * * 1 /path/to/run-content-pipeline.sh "weekly topic"For teams that want CI/CD-style orchestration, GitHub Actions gives you artifact passing between stages, retry logic, and visibility into what ran and when:
# .github/workflows/content-pipeline.yml
name: Content Pipeline
on:
schedule:
- cron: '0 9 * * 1' # Mondays at 9am UTC
workflow_dispatch:
inputs:
topic:
description: 'Content topic'
required: true
jobs:
research:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run researcher
run: |
claude --prompt "Research: ${{ inputs.topic }}"
- uses: actions/upload-artifact@v4
with:
name: research
path: .agents/outputs/research-*.md
write:
needs: research
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/download-artifact@v4
- name: Run writer
run: |
claude --prompt "Write about: ${{ inputs.topic }}"
- uses: actions/upload-artifact@v4
with:
name: draft
path: .agents/outputs/draft-*.mdExpanding to Multiple Squads
Once your content squad works reliably, you have a template for adding more squads. The directory structure scales naturally:
.agents/
├── squads/
│ ├── content/ # Content production
│ │ ├── SQUAD.md
│ │ ├── researcher.md
│ │ ├── writer.md
│ │ └── editor.md
│ ├── engineering/ # Code quality
│ │ ├── SQUAD.md
│ │ ├── code-reviewer.md
│ │ ├── test-writer.md
│ │ └── debugger.md
│ └── intelligence/ # Research & monitoring
│ ├── SQUAD.md
│ ├── competitor-tracker.md
│ └── market-analyst.md
└── memory/
├── content/
├── engineering/
└── intelligence/Squads can reference each other’s outputs for cross-squad coordination. For example, your content writer can check if the intelligence squad has relevant competitor briefs or market reports before drafting, pulling from .agents/memory/intelligence/competitor-briefs/ and .agents/memory/intelligence/market-reports/. This is how specialized squads become more than the sum of their parts — each squad’s output enriches the others.
Key Takeaway — File-based memory is the simplest effective approach. A shared markdown file per squad that every agent reads at start and writes at finish solves 80% of coordination issues. The learnings file becomes institutional knowledge that compounds over time.
Going to Production
Running agent teams on your laptop is one thing. Running them reliably enough to trust with real business operations is another. Here is what matters before you make the switch.
Configuration. Every agent needs instructions clear enough that you could hand them to a new hire and get consistent output. Match model selection to task complexity — use Sonnet for straightforward tasks like research and writing, reserve Opus for judgment-heavy work like editing and review. Scope tool access to only what each agent needs; a writer has no reason to access web search if the researcher already compiled the brief. Initialize all memory paths before the first run so agents don’t fail on missing files.
Quality gates. Each agent should have explicit quality standards (word counts, source minimums, score thresholds) so you can evaluate output programmatically, not just by feel. Add quality gates between pipeline stages — the editor should be able to reject a draft and trigger a revision loop rather than polishing something fundamentally flawed. Define what happens when an agent fails: does the pipeline stop, retry, or fall back to a simpler approach? And keep a human review step before any final output goes live, at least until you have enough data to trust the pipeline’s judgment.
Operations and cost control. Log every agent run including inputs, outputs, token usage, and wall-clock time. Monitor costs weekly — a pipeline that seems cheap per-run can get expensive at scale if agents are verbose or retry frequently. Test your schedule with dry runs before letting it operate unattended. Have a rollback plan: if agents produce bad output, you need to catch it before it reaches customers and revert to the last known-good version.
Security. Agents should never have access to secrets they don’t need. Review outputs before publishing, especially when agents have web access and could inadvertently include sensitive information. Respect API rate limits in your orchestration scripts. And avoid storing PII in agent memory unless there is a clear business reason and you have a plan for data retention.
Important — Match model selection to task complexity: Sonnet for straightforward tasks like research and writing, Opus for judgment-heavy work like editing and review. Scope tool access to only what each agent needs.
Common Workflow Patterns
These patterns come up repeatedly when operating agent teams. You will likely need at least one of them within your first week.
Approval gates let you pause the pipeline for human review between stages. This is especially useful early on when you are still tuning agent instructions and want to catch issues before they compound:
# After writer, before editor
echo "Draft ready for review: .agents/outputs/draft-${SLUG}.md"
read -p "Approve to continue? (y/n) " approval
if [ "$approval" != "y" ]; then
echo "Pipeline stopped for revision"
exit 1
fiConditional routing sends work to different specialist agents based on the input. A comparison post needs a different structure than a tutorial, and routing at the orchestration layer is simpler than making one writer handle every format:
# Detect content type and route
if [[ "$TOPIC" == *"vs"* ]]; then
claude --prompt "Use comparison-writer agent..."
elif [[ "$TOPIC" == *"tutorial"* ]]; then
claude --prompt "Use tutorial-writer agent..."
else
claude --prompt "Use general-writer agent..."
fiFeedback loops let the editor send work back to the writer rather than trying to fix everything itself. Add this to your editor agent’s instructions: if any quality score falls below 6, document the specific issues, output a revision request to .agents/outputs/revision-request-{topic}.md, and have the writer address those issues before the editor re-reviews. This mirrors how real editorial teams work and produces better output than a single pass.
Next Steps
You’ve built your first AI agent team with Claude. From here:
-
Iterate on prompts: The agent instructions are the product. Refine them based on output quality.
-
Add monitoring: Track success rates, token costs, and time-to-completion.
-
Expand carefully: Add agents only when you have clear specialization needs.
-
Document learnings: Your memory files become institutional knowledge.
For advanced patterns, see:
Building production agent teams? Contact us for architecture reviews or check our consulting services for hands-on implementation support.
