Claude Code agents let you split one overloaded conversation into specialists, a researcher, a writer, and a reviewer, each with its own context window, tools, and instructions. This lesson covers the agent file format (frontmatter plus markdown body) and how to run agents sequentially or in parallel for content production.
What you will be able to do
- Create custom agent files in .claude/agents/ with YAML frontmatter and a markdown instructions body
- Restrict an agent's tools, for example disallowedTools: Write, Edit, so a reviewer can find issues without silently fixing them
- Chain agents in a sequential pipeline where the researcher's brief feeds the writer and the writer's draft feeds the reviewer
- Run several agent instances in parallel to cut research time roughly in half
- Write specific, checklist-style instructions instead of vague ones so an agent's output is actionable, not just a vibe check
Before you start
- Claude Code installed, with basic comfort writing prompts and reading YAML frontmatter
- MCP servers already connected, such as Perplexity and Firecrawl, if the researcher agent should reach the web (covered in an earlier lesson)
- A brand voice guide or content rules file the writer and reviewer agents can read, such as a brand-config.json or playbook doc
- A drafts/ folder or similar location where the writer agent can save output for the reviewer to check
Reference
| Field | What it controls | Example from the lesson |
|---|---|---|
| name | Agent identifier; the filename becomes the agent name | researcher |
| description | How Claude Code decides when to auto-spawn this agent; written like a job posting | "Deep web research on any topic. Searches the web, reads competitor articles, produces research briefs." |
| tools | Which tools the agent is allowed to use | WebSearch, WebFetch, Read, Glob, Grep |
| disallowedTools | Tools explicitly blocked, used to enforce a role | Write, Edit (blocked on the reviewer so it can't silently fix issues) |
| model | Which model the agent runs on | sonnet |
| memory | Whether the agent keeps what it learns between sessions | project |
| maxTurns | Cap on tool round-trips per run, stops a curious agent from chasing tangents | 20 |
| skills | Skill files preloaded into the agent's context at startup | seo-check |
Common errors and fixes
| What goes wrong | The fix |
|---|---|
| Reviewer agent scores every draft 9/10 and flags zero critical issues | The instructions said "check brand voice" instead of listing every forbidden phrase and every structure rule with pass or fail criteria; write an exhaustive, specific checklist |
| Reviewer given Write and Edit access quietly fixes problems instead of reporting them, so the same mistake keeps recurring in later drafts | Set disallowedTools: Write, Edit on the reviewer so it can only surface issues with a location and suggestion |
| One long conversation handles research, writing, and review together and forgets the early research by the time it reaches quality checks | Split the work across separate agents, each with its own context window, instead of one generalist conversation |
| A researcher agent burns 80+ tool calls chasing one tangent | Set maxTurns to cap the number of tool round-trips per run |
| Writer agent wanders off the research brief into its own web searches | Give the writer agent no web tools, only Read, Write, Edit, Glob, Grep, so it stays tied to the brief and brand guide |
Read the full walkthrough
The complete lesson, with screenshots and any downloads, is published on Substack as part of Claude Code Masterclass: Build AI Systems Without Writing Code.
More in this section
Continue the course
Browse all lessons in the Claude Code Masterclass: Build AI Systems Without Writing Code course, or subscribe to the GenAI Unplugged newsletter to get new lessons in your inbox.
