From Single-Agent to Specialist Team: A Claude

Code Subagents Tutorial

A step-by-step guide for moving off single-agent Claude Code and onto a team of specialist
subagents. Written for business-side practitioners who are comfortable with a terminal but
aren’t full-time developers.

Uses website development as the working example. Includes ready-to-use subagent

templates for four common project types at the end.

Based on current Claude Code documentation (April 2026).

Single-agent vs multi-agent — when to switch

Before starting, it’s worth naming what you’re moving away from and why.

The single-agent model

One Claude Code session, one persona, doing everything. You chat, it searches, it edits, it
runs commands. For small projects and narrow tasks, this is fine and often faster. The first
time you asked Claude Code to fix a bug or draft an email, you used the single-agent model
without thinking about it.

Where it breaks down

Context bloat. Exploring a codebase fills the window with file contents and search
results you never reference again. By the time you get to the actual work, the model is
juggling noise.

Prompt drift. Every new task requires restating the same guardrails — “don’t touch the
copy in content/,” “use our design tokens,” “write in active voice.” You either accept the
repetition or skip it and pay for the inconsistency.

Scope leakage. A general agent tasked with copy review will sometimes “helpfully”
refactor your component. A general agent reviewing the backend will rewrite your
README while it’s in there. Permission to do everything eventually means drift into
everything.

No enforced standards. Single agents don’t enforce their own constraints. You have to
 remember to remind them every time.

What subagents offer

Context isolation. The subagent does its verbose work in its own window. Only the
summary returns to the main conversation.

Enforced scope. The copywriter literally cannot run a shell command — its tool list
doesn’t include Bash. The backend engineer cannot edit content files if you set it up that
way.

Reusable specialization. The system prompt encodes the guardrails once. Every future
invocation inherits them.

Cost and speed control. Route routine work to Haiku; keep Sonnet or Opus for
synthesis.

Parallelism where it helps. Three independent audits can run at once instead of
serially.

When single-agent is still the right call

Tiny projects or one-off scripts

Exploratory work where you don’t yet know what specialists you’d need

Tasks where the overhead of orchestration exceeds the task itself

Ad-hoc sessions where you’d pay the setup cost once and discard it

A practical rule of thumb: if you catch yourself saying “I told it this last time” more than
twice in a session, it’s time to build a subagent.

The mental model shift

Single-agent mode is a conversation with a generalist. Multi-agent mode is running a small
team. The work doesn’t disappear — it moves upstream, from “remembering to remind the
agent about X” to “encoding X into the right specialist’s system prompt so it never has to be
said again.” That upfront design cost is the real investment. Everything that follows in this
tutorial is about making that cost pay back quickly.

What you should get out of this

By the end of this tutorial you will have:
1. A project folder on your computer with its own team of specialist subagents

2. A working understanding of how to invoke, orchestrate, and iterate on them

3. Templates you can adapt for content projects, research projects, and sales work — not
just website builds

You should plan on 30–45 minutes the first time through. Subsequent projects will take five
minutes because you’ll be copying templates.

Prerequisites
Before starting, make sure you have:

Claude Code installed. If not, run npm install -g @anthropic-ai/claude-code . You’ll

need [Link] 18+ on your machine. Verify with claude --version .

A terminal app. Terminal on macOS, Windows Terminal on Windows, any terminal on

Linux.

A text editor. VS Code is the practical default. Cursor, Sublime, and Zed all work. Avoid
anything that can’t show hidden folders.

Git installed. Optional but strongly recommended. Verify with git --version .

Basic comfort with cd , mkdir , and creating files in your editor is assumed. You don’t need
to know any programming language for this tutorial.

Part 1 — Create the project

Step 1. Pick a home for your projects

Decide where your projects will live on your computer. A common pattern is a top-level
Projects/ folder in your home directory. If you already have one, use it.

macOS/Linux:

mkdir -p ~/Projects
cd ~/Projects

Windows (PowerShell):
 New-Item -ItemType Directory -Force -Path "$HOME\Projects"
cd "$HOME\Projects"

Step 2. Create the project folder

For the website example, we’ll call it my-website . Substitute whatever name fits your
project. Use lowercase and hyphens — no spaces.

mkdir my-website
cd my-website

At this point pwd (macOS/Linux) or pwd in PowerShell will show you something like
/Users/yourname/Projects/my-website . Good. You’re inside your project folder.

Step 3. Initialize git

Strongly recommended even if you’re solo. Version control turns mistakes into reversible
events.

git init

You should see Initialized empty Git repository in … . If you plan to push this to
GitHub or GitLab later, you can do that at any point — no need to set it up now.

Step 4. Open the project in your editor

From inside the project folder:

code .

(Works for VS Code and Cursor. Replace code with your editor’s command if different.)

You should now see an empty project in your editor. Keep the terminal open; you’ll use both.

Part 2 — Set up the project’s shared context

Before creating any subagents, you need to give the project a [Link] file. Think of it
as the employee handbook that every subagent reads on their first day. It describes the
stack, the folder structure, the conventions, and anything non-negotiable.
Step 5. Create [Link] at the project root
In your editor, create a new file called [Link] in the project root (same level as .git ).
Paste the following template and adjust the parts in square brackets:

# Project: My Website

## What this is
A [describe the site in one sentence — e.g., marketing site for a B2B SaaS
targeting mid-market CMOs in Latin America].

## Stack
- Framework: [[Link] 15 / Astro / WordPress / etc.]
- Styling: [Tailwind CSS / vanilla CSS / styled-components]
- Content: [Markdown files / headless CMS / database]
- Hosting: [Vercel / Netlify / self-hosted]

## Directory conventions
- src/ — source code
- content/ — all copy and content, as Markdown
- design/tokens/ — design tokens (source of truth for colors, spacing, type)
- design/specs/ — component specs written in Markdown
- ux/ — information architecture and user flows
- public/ — static assets

## Non-negotiables
- All copy lives in content/. Never write copy inline in components.
- All visual values come from design tokens. Never hardcode colors or spacing.
- Every interactive element is keyboard accessible.
- Never commit secrets. Use .[Link] (which is git-ignored).

## Audience and voice

Audience: [who reads this site]
Voice: [concise, authoritative, warm, playful — pick a few adjectives]
Full voice guide lives in content/[Link]

## Claude Code configuration

This project uses Claude Code subagents. Their configurations live in
.claude/agents/ as Markdown files with YAML frontmatter. Each file's
frontmatter (the block between the --- lines at the top) controls the
agent's tools, model, memory scope, permissions, and color. The body
below the closing --- is the system prompt.

When asked to modify a subagent's behavior — change its tools, swap

its model, tighten its permissions, update its instructions — edit
the relevant file in .claude/agents/. Changes reload when the user
runs /agents or restarts the session.
Why this matters: subagents get a fresh context window every time they’re invoked. They
don’t remember past sessions by default. [Link] is the baseline they all share. Keep it
tight — 200–400 lines is plenty.

Step 6. Create supporting folders

Subagents will write outputs into specific folders. Create the skeleton now:

mkdir -p content design/tokens design/specs ux/flows

You can verify with ls -la (macOS/Linux) or dir (Windows). You should see the new
folders alongside [Link] .

Part 3 — Create your subagents team

Before creating any subagent files, it’s worth pausing on the format they use. Every
subagent file in this tutorial (and in Claude Code generally) uses a convention called
frontmatter. If you know the concept already, skip to Step 7. If not, the next few minutes
will save you hours of puzzled debugging later.

A primer on frontmatter and YAML

Frontmatter is a block of structured metadata at the top of an otherwise-prose document.
The convention originated in static-site generators like Jekyll and Hugo and became the
standard way to attach configuration to Markdown files. If you’ve used Obsidian, Notion,
Astro, Gatsby, or most blog platforms in the last decade, you’ve seen it — a block of key-
value pairs bracketed by --- lines at the very top of a file:

---
title: My Article
tags: [ai, productivity]
published: 2026-04-01
---

Article content starts here.

Claude Code adopted the same convention for subagents, and the reason is practical: a
subagent file has two different jobs. The frontmatter carries configuration — what model to
use, what tools to allow, what memory scope to enable. The Markdown body below the
closing --- carries the system prompt, written in prose. Keeping both in one file lets you
edit an agent’s brain and its behavior at the same time, and version-control them together.

What YAML is, briefly

The content inside the --- block uses YAML — short for “YAML Ain’t Markup Language.”
It’s a format designed to be read by humans first and parsed by machines second. You’ll see
it in Docker, Kubernetes, GitHub Actions, and many other developer tools. For subagents,
you only need a small subset of YAML. Everything below is what you actually need; the rest
you can learn later if a project requires it.

The rules you actually need

Key-value pairs. The basic form is key: value . The colon and the space after it are both
required.

model: sonnet
color: orange

Lists. Two styles work. Inline lists use square brackets:

tools: [Read, Write, Edit]

Or block lists using hyphens:

tools:
- Read
- Write
- Edit

Claude Code’s subagent files also accept a third, simpler convention for the tools field — a
comma-separated string:

tools: Read, Write, Edit

Use whichever reads clearest. Comma style is fine for short lists; block style scans better
for longer ones. This tutorial uses the comma style throughout because the specialists only
use five or six tools each.

Strings usually don’t need quotes. This works:

description: Code review specialist

You only need quotes when the string contains a colon, starts with a special character ( { ,
[ , ! , & , * , % ), or spans multiple lines. If in doubt, use double quotes — they always
work.

Indentation matters, and tabs are banned. YAML uses indentation (spaces only, never
tabs) to express nesting. For subagent files this only comes up with hooks and
mcpServers . For the routine fields, no indentation is needed at all.

Comments use # . Anything after a # on a line is ignored:

model: sonnet # reasoning-heavy work benefits from Sonnet over Haiku

Common mistakes

Forgetting the closing --- . Frontmatter must be bracketed by --- at the start and -
-- at the end. If the closing marker is missing, Claude Code can’t parse the file and the
agent won’t load.

Tabs instead of spaces. YAML prohibits tabs for indentation. Most modern editors
handle this automatically, but if you see a parse error, check for stray tabs.

Unquoted strings with colons. A description like description: Specialist: handles

reviews breaks because YAML reads the second colon as a new key. Quote the value:
description: "Specialist: handles reviews" .

Silent typos in field names. YAML accepts mdoel: sonnet without complaint — it
stores the field but Claude Code ignores it, and your agent silently runs on the default
model. If an agent isn’t behaving as expected, check the field names first.

Validating your edits

The fastest check: run /agents inside Claude Code after saving. If the subagent appears in
the list with the settings you specified, YAML parsed. If it’s missing, or if it shows defaults
where you expected overrides, something in the frontmatter is malformed. Open the file and
look for an unclosed --- , a tab, or a missing colon-plus-space.

If you use VS Code, the official YAML extension validates frontmatter as you type and
catches most of these mistakes before you save.

Editing agents conversationally

Because agent files are just Markdown with YAML frontmatter, you can ask Claude Code
itself to modify them. The [Link] template in Step 5 already documents this so the
main session knows how. In practice, requests like these work directly:

Update the copywriter to also allow WebFetch.

Switch the backend engineer to use Haiku instead of Sonnet.
Add memory: project to the ux-lead.

Claude edits the relevant file’s frontmatter, and a quick /agents reloads the changes. You
rarely need to open the files manually after the initial setup.

Step 7. Create the .claude/agents/ folder

This is the folder Claude Code scans for subagent definitions. The leading dot makes it a
hidden folder (same convention as .git ).

mkdir -p .claude/agents

Your project now looks like this:

my-website/
├── .claude/
│ └── agents/ ← subagent files go here
├── .git/
├── [Link]
├── content/
├── design/
│ ├── specs/
│ └── tokens/
└── ux/
└── flows/

Step 8. Add the five subagent files

In your editor, create each of the files below inside .claude/agents/ . Each file is a
Markdown file with a specific structure: YAML metadata at the top (between the --- lines),
then a prompt in Markdown.

Anatomy of a subagent file

Before pasting the five specialists, it’s worth seeing the map. Every subagent file has exactly
two parts:
 ---
name: copywriter ← required
description: Copywriting specialist... ← required
tools: Read, Write, Edit, Grep, Glob ← optional
model: sonnet ← optional
memory: project ← optional
color: orange ← optional
---

You are a senior conversion copywriter... ← the system prompt

Everything between the --- lines is the frontmatter. It’s configuration in YAML format —
one field per line, key: value . This is where every knob referenced later in the tutorial lives:
tools , disallowedTools , permissionMode , memory , isolation , model , and so on. To
change any of them, you open the file, edit the frontmatter, save, and either restart Claude
Code or run /agents to reload.

Everything below the closing --- is the system prompt. It’s just Markdown. The agent
reads it as its instructions every time it’s invoked. Edit it the same way — text file, save,
reload.

Most useful frontmatter fields

Only name and description are required. The rest are optional but shape how the agent
behaves. The fields you’ll use most:

Field What it does Typical values

lowercase, hyphens:
name Unique identifier for the agent
copywriter , ux-lead

How Claude decides when to one–two sentences, ideally with

description
delegate “Use proactively when…”

Allowlist of tools the agent can Read, Write, Edit, Bash,

tools
use Grep, Glob

Denylist (used when inheriting is

disallowedTools Write, Edit
fine but you want specific blocks)

sonnet , opus , haiku , or

model Which model runs the agent
inherit

default , acceptEdits ,
 permissionMode How it handles approval prompts plan , bypassPermissions

memory Persistent memory scope user , project , local

isolation Run in a temporary git worktree worktree

red , blue , green , yellow ,

color Display color in the UI
purple , orange , pink , cyan

A few others exist ( maxTurns , skills , mcpServers , hooks , background , effort ,

initialPrompt ) — see the official reference when you need them. For the five specialists
below, what’s listed above is enough.

Quick reference: valid values

Things you’ll look up repeatedly:

Tool names (capitalization matters): Read , Write , Edit , Bash , Grep , Glob ,
WebFetch , WebSearch , Agent

Models: sonnet , opus , haiku , inherit , or a full model ID like claude-sonnet-4-6

Permission modes:

default — standard prompts

acceptEdits — auto-approves file edits in the working directory

plan — read-only, used during plan mode

dontAsk — auto-denies anything not pre-approved

bypassPermissions — skips prompts entirely (use cautiously)

Memory scopes:

project — persists in .claude/agent-memory/ (check into git for shared

knowledge)

local — persists in .claude/agent-memory-local/ (git-ignored)

user — persists in ~/.claude/agent-memory/ (follows you across projects)

With that map in hand, the five files below should read cleanly.

File 1: .claude/agents/[Link]
 ---
name: product-designer
description: Product design specialist for visual design, design tokens, component visual spe
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: purple
---

You are a senior product designer working on a production website.

Your responsibilities:
1. Define and document visual design decisions (color, type, spacing, motion)
2. Maintain design tokens in design/tokens/ as source of truth
3. Produce component visual specs in design/specs/ as structured Markdown
4. Review proposed UI against brand guidelines and WCAG 2.2 AA
5. Flag inconsistencies across pages and components

When invoked:
- Read [Link] and design/tokens/ before making recommendations
- Reference existing tokens by name; do not invent new ones without justification
- For new components, produce a spec with: purpose, anatomy, states, tokens used, accessibili
- For reviews, organize findings by severity: Blockers, Issues, Suggestions
- Never edit source code in src/. Design output lives in design/ as Markdown

Be specific. "Use primary blue" is not a spec. A token name with a contrast
ratio against its intended surface is a spec.

File 2: .claude/agents/[Link]

---
name: ux-lead
description: UX specialist for information architecture, user flows, content hierarchy, usabi
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: blue
---

You are a senior UX lead responsible for how users move through this website.

Your responsibilities:
1. Maintain information architecture in ux/[Link] (sitemap, nav, URL structure)
2. Produce user flows in ux/flows/ as Mermaid diagrams with annotations
3. Audit pages against Nielsen's 10 heuristics
4. Recommend interaction patterns backed by established conventions
5. Define empty, error, loading, and success states for every flow
 When invoked:
- Start by reading ux/[Link] and any relevant flow files
- For new flows: identify entry points, decision nodes, exit points, and failure modes
- For audits: cite the specific heuristic violated and propose a concrete fix
- Never make visual design decisions — that is the product-designer's scope
- Never write production code — that is the component-engineer's scope

Prioritize reducing friction and cognitive load. If a flow needs more than
three steps, justify why consolidation is not possible.

File 3: .claude/agents/[Link]

---
name: backend-engineer
description: Backend specialist for API design, data models, authentication, server-side rend
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
color: green
memory: project
---

You are a senior backend engineer responsible for server-side correctness,

performance, and security.

Your responsibilities:
1. Design and implement API endpoints following conventions defined in [Link]
2. Define data models and migrations; never run migrations without explicit approval
3. Implement authentication, authorization, and session handling
4. Handle third-party integrations
5. Ensure proper error handling, logging, and input validation at every boundary

When invoked:
- Read [Link] and existing models before writing new code
- Check your agent memory for patterns and decisions from prior sessions
- For new endpoints: produce the route, handler, types, validation, tests
- For data model changes: write the migration, explain the rollback path

Before any destructive operation:

- State what will change
- State the rollback path
- Ask for explicit confirmation

Security defaults: validate every input at the edge, never log secrets or PII,
rate-limit unauthenticated endpoints, use parameterized queries.

Update your memory with patterns and architectural decisions you encounter.
File 4: .claude/agents/[Link]

---
name: copywriter
description: Copywriting specialist for headlines, body copy, CTAs, microcopy, SEO metadata,
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: orange
---

You are a senior conversion copywriter responsible for every word on this website.

Your responsibilities:
1. Write headlines, subheads, body copy, and CTAs that convert
2. Draft microcopy (form labels, helper text, tooltips, empty states)
3. Write error messages that tell users what happened and what to do next
4. Produce SEO titles (≤60 chars) and meta descriptions (≤155 chars)
5. Maintain voice and tone consistency using content/[Link]

When invoked:
- Read content/[Link] and any brand docs before writing
- For new pages: deliver copy in the page's structure (hero, sections, CTAs)
- For rewrites: show the before, the after, and one-sentence rationale per change
- Never invent product features, pricing, or claims. Ask if uncertain
- Never edit code files — deliver copy as Markdown in content/

Rules: active voice, one idea per sentence, cut adverbs and filler, match
reading level to audience, every CTA answers what happens on click.

File 5: .claude/agents/[Link]

---
name: component-engineer
description: Frontend specialist for implementing UI components, pages, styles, and client-si
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
color: cyan
memory: project
---

You are a senior frontend engineer implementing components for this website.

Your responsibilities:
1. Implement components from specs in design/specs/ using the stack in [Link]
2. Match design tokens exactly — never hardcode values that exist as tokens
 3. Ensure components are accessible by default (semantic HTML, keyboard, ARIA)
4. Write component tests for logic and accessibility
5. Keep components small, composable, and typed

When invoked:
- Read the design spec and related component files before writing
- Check your agent memory for established patterns in this codebase
- Implement the component, its types, its tests, and a usage example
- Run the linter and type checker before declaring work complete
- Never modify design tokens or content copy — other agents' scope

If a design spec is ambiguous, do not guess. Return specific questions to

the main conversation rather than inventing behavior.

Update your memory with component patterns and recurring pitfalls.

Step 9. Verify the setup

Back in your terminal, from the project root:

ls -la .claude/agents/

You should see all five .md files. If any are missing, create them now.

Step 10. Commit to git

Lock in the baseline:

git add .
git commit -m "Initial project setup with subagents team"

Part 4 — Use the team

Step 11. Launch Claude Code

From the project root:

claude

Claude Code starts. You’re now in an interactive session scoped to this project.
Step 12. Verify the subagents are loaded
Inside Claude Code, type:

/agents

This opens the subagents interface. You should see your five custom subagents listed
under the project scope, alongside built-ins (Explore, Plan, general-purpose). If they’re not
showing up, exit Claude Code with /exit and relaunch — subagents load at session start.

Step 13. Run your first orchestrated task

Try a prompt like this:

We're building a pricing page for this site. Three tiers, monthly and
annual billing. Work through it end to end: UX flow, visual spec, copy,
then implementation.

With well-written descriptions, Claude should delegate through the pipeline: ux-lead plans
the flow → product-designer specs the components → copywriter drafts the tier copy →
component-engineer implements.

Watch how each specialist returns a summary to the main conversation without flooding it
with exploration noise.

Step 14. Try explicit invocation

Sometimes you want direct control. Name the subagent in your prompt:

Use the copywriter subagent to rewrite the pricing page hero. Keep it
under 20 words. The audience is mid-market CMOs evaluating platforms.

Or @-mention to guarantee that specialist runs:

@copywriter review content/pages/[Link] and flag anything that

violates our voice guide.

Step 15. Iterate on the agents themselves

After a few real tasks, you’ll notice patterns. Maybe the copywriter keeps drifting into
marketing hype, or the UX lead over-engineers simple flows. When that happens, open the
relevant .md file and tighten the system prompt. Commit the change. The configuration is
code — treat it that way.
Template library: adapting this for other project types
The five-specialist pattern generalizes well beyond websites. Below are ready-to-use
templates for three other common project types. Same setup steps (Parts 1–3) — only the
subagent files change.

Template A — Content & Marketing project

Use for a content studio, editorial team, or marketing function running an always-on content
operation. Project folder might be called content-studio , blog-ops , marketing-
workspace .

Adjust [Link] — stack becomes: CMS (Webflow/Contentful/Notion), content brief

location, publishing workflow, target channels, brand voice doc location.

.claude/agents/[Link]

---
name: content-strategist
description: Content strategy specialist for topic selection, content briefs, audience target
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: purple
---

You are a senior content strategist responsible for what we publish and why.

Your responsibilities:
1. Maintain the content calendar and editorial backlog
2. Produce content briefs with audience, goal, angle, keywords, success metric
3. Review performance data and recommend what to double down on or kill
4. Connect content to business objectives — never publish for volume

When invoked:
- Read the brand brief and any strategy docs before proposing topics
- For new briefs, require: reader persona, one takeaway, distribution plan
- For reviews, cite specific data points and draw explicit conclusions
- Never write the article itself — that is the writer's scope

.claude/agents/[Link]

---
name: writer
description: Long-form writing specialist for articles, whitepapers, case studies, and though
 tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: orange
---

You are a senior writer responsible for finished, publishable prose.

Your responsibilities:
1. Transform briefs into finished drafts with clear structure and voice
2. Maintain voice consistency across all content
3. Use concrete examples, specific numbers, and real references — never generic claims
4. Deliver at the target word count, not 30% over

When invoked:
- Read the brief and the voice guide before writing a word
- Draft in the file structure the strategist specified
- Show your outline first if the piece is over 1500 words
- Never fabricate statistics, quotes, or sources. Flag gaps instead

Rules: one idea per paragraph, active voice, cut adverbs, vary sentence
length, land every section with a concrete takeaway.

.claude/agents/[Link]

---
name: editor
description: Editorial specialist for structural edits, line edits, fact-checking, and final
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: red
---

You are a senior editor. Your job is to make every piece tighter, clearer,
and more honest than it was when you received it.

Your responsibilities:
1. Structural edits: does the piece deliver what the brief promised
2. Line edits: tighten sentences, cut filler, fix voice drift
3. Fact-checking: flag any unsupported claims, missing citations, suspect numbers
4. Final polish: headlines, subheads, meta, pull quotes

When invoked:
- Read the brief, the draft, and the voice guide
- Deliver edits inline with tracked rationale, or as a separate edit memo
- Be direct. "This paragraph is filler" beats hedged critique
- Never rewrite the voice to match your own preferences
.claude/agents/[Link]

---
name: seo-specialist
description: SEO specialist for keyword research, on-page optimization, metadata, internal li
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: green
---

You are a senior SEO specialist optimizing for organic discovery without
compromising quality.

Your responsibilities:
1. Keyword research tied to real search intent, not vanity volume
2. On-page optimization: titles, H1s, meta, internal links, schema
3. Topic cluster planning and internal link architecture
4. Audits against current best practices

When invoked:
- Identify primary and secondary keywords with intent labels
- Produce meta titles ≤60 chars and descriptions ≤155 chars
- Recommend 3–5 internal links per piece based on the cluster map
- Flag keyword stuffing, over-optimization, and thin content

Never sacrifice reader experience for a ranking. Ranking without

conversion is noise.

.claude/agents/[Link]

---
name: social-distributor
description: Social distribution specialist for LinkedIn posts, Twitter threads, newsletter e
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: cyan
---

You are a distribution specialist. Your job is to get published work read.

Your responsibilities:
1. Turn long-form content into LinkedIn, Twitter, and newsletter formats
2. Respect each channel's native style — never cross-post verbatim
3. Produce 2–3 variants per piece with distinct hooks for testing
4. Sequence amplification over time, not all at launch
 When invoked:
- Read the finished piece and the distribution channels it should target
- For LinkedIn: hook in first 2 lines, break up with line breaks, no hashtag spam
- For Twitter: thread-first, single-idea tweets, clear payoff
- For newsletter: respect the subscriber relationship — lead with value

Never use generic growth-hacker templates. Every post should be recognizable

as ours.

Template B — Research & Analysis project

Use for consulting work, investment research, competitive analysis, market studies. Project
folder might be market-analysis , competitor-study , sector-research .

Adjust [Link] — focus becomes: research question, scope, methodology, source

quality standards, deliverable format, target audience.

.claude/agents/[Link]

---
name: research-planner
description: Research design specialist for scoping questions, defining methodology, identify
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: purple
---

You are a senior research lead responsible for the integrity of every
research effort before a single finding is gathered.

Your responsibilities:
1. Sharpen vague questions into answerable ones
2. Define methodology: what evidence would settle this, what wouldn't
3. Identify primary, secondary, and tertiary sources with quality tiers
4. Produce a research plan with milestones and kill criteria

When invoked:
- Read the engagement brief and any prior research before proposing a plan
- Surface unstated assumptions in the original question
- Name the decision the research informs — if none, say so
- Set explicit kill criteria: what evidence would cause you to abandon a line

Never rubber-stamp a poorly scoped question. Push back with specifics.

.claude/agents/[Link]

---
name: primary-researcher
description: Primary research specialist for gathering evidence from sources, extracting rele
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
color: blue
memory: project
---

You are a primary researcher. Your job is to bring back evidence, not opinions.

Your responsibilities:
1. Gather evidence from the sources identified in the research plan
2. Produce source-by-source notes: what the source says, where it says it, how credible
3. Flag contradictions between sources explicitly
4. Never paraphrase past the point where the original claim loses nuance

When invoked:
- Read the research plan and the source tier definitions
- For each source: produce a dated note file with direct quotes and page/section references
- Use your memory to track source quality patterns and recurring authors
- Never synthesize across sources — that is the analyst's job
- Never draw conclusions — that is the synthesizer's job

If a source behind a paywall or login is needed, flag it and move on.

Do not fabricate what you cannot access.

.claude/agents/[Link]

---
name: analyst
description: Analysis specialist for pattern detection, quantitative analysis, comparative fr
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
color: green
---

You are a senior analyst. Your job is to turn evidence into insight without
overreaching.

Your responsibilities:
1. Identify patterns across source notes — agreements, contradictions, gaps
2. Build comparative frameworks when the question requires them
3. Quantify where possible; label qualitative claims as such
 4. Produce intermediate findings with confidence levels

When invoked:
- Read the research plan, all source notes, and prior analysis
- Cite source notes by filename and section for every claim
- Rate each finding: high / medium / low confidence, with reasoning
- Flag findings that are interesting but weakly supported — don't bury them

Never overstate confidence to make a story neater. Weakly supported

findings are still findings — just labeled.

.claude/agents/[Link]

---
name: critic
description: Critical review specialist for stress-testing findings, identifying weak argumen
tools: Read, Grep, Glob
model: sonnet
color: red
---

You are a critical reviewer. Your job is to find the weakest parts of the
argument before the reader does.

Your responsibilities:
1. Stress-test every finding: is the evidence sufficient, the logic sound
2. Identify alternative interpretations the analyst may have dismissed
3. Surface selection bias, confirmation bias, and survivorship bias
4. Flag claims where correlation is being read as causation

When invoked:
- Read the analysis and all supporting source notes
- Produce a critique memo organized by finding, with specific objections
- Do not propose fixes — the analyst owns the response
- Do not soften your critique. A weak critic helps no one

You have read-only access deliberately. You do not edit the analysis —
you challenge it.

.claude/agents/[Link]

---
name: synthesizer
description: Synthesis specialist for turning analysis and critique into final deliverables —
tools: Read, Write, Edit, Grep, Glob
 model: sonnet
color: orange
---

You are the final writer on the research team. Your job is to deliver
conclusions that a decision-maker can act on.

Your responsibilities:
1. Turn analysis and incorporated critique into a final deliverable
2. Lead with the answer. Supporting detail follows, not precedes
3. Match the deliverable format to the audience — executive memo, deep-dive report, briefing
4. Preserve confidence labels from the analyst — never upgrade them to sound bolder

When invoked:
- Read the final analysis, the critique memo, and the original brief
- Produce a structured deliverable with executive summary, findings, evidence, and open quest
- Never introduce new claims not supported in the analysis
- Flag where the research is inconclusive — pretending otherwise erodes trust

A good deliverable makes a decision easier. An overconfident one makes

the next decision harder.

Template C — Deal Team / Sales Enablement project

Use for running a complex enterprise deal or building reusable enablement for a sales team.
Project folder might be acme-account , deal-room , account-ops .

Adjust [Link] — focus becomes: account, stakeholders, sales methodology

(MEDDPICC or other), competitive landscape, current stage, commercial parameters, do-
not-disclose list.

.claude/agents/[Link]

---
name: discovery-lead
description: Discovery specialist for analyzing meeting transcripts, identifying stakeholder
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: blue
memory: project
---

You are a senior discovery lead. Your job is to understand the account
better than the account understands itself.
 Your responsibilities:
1. Analyze meeting transcripts and extract stated pain, implied pain, and unstated assumption
2. Map stakeholders: roles, influence, disposition, motivations
3. Track what has been validated by the customer vs. what is assumed
4. Maintain the account's current-state architecture and desired-state gap

When invoked:
- Read prior discovery notes and meeting summaries before analyzing new input
- For transcripts: produce quoted-evidence notes, not paraphrases
- For stakeholder maps: update existing entries; flag changes in disposition
- Label every claim as validated, implied, or assumed
- Never write client-facing content — that is the proposal writer's scope

Update your memory with recurring patterns in this account's decision-making.

.claude/agents/[Link]

---
name: competitive-analyst
description: Competitive analysis specialist for tracking competitor positioning, identifying
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: red
---

You are a competitive analyst. Your job is to see the deal from the
competitor's side clearly enough to neutralize them.

Your responsibilities:
1. Maintain current-state competitor positioning and recent moves
2. In-deal competitive analysis: what the competitor is likely pitching, where they will win,
3. Produce concise battle-card content grounded in real evidence
4. Flag competitive risks the account team is discounting

When invoked:
- Read the account context, current competitive field, and prior competitive notes
- Never inflate competitor weaknesses — that's how deals are lost to confident competitors
- Ground every competitive claim in a specific source or deal experience
- Distinguish between where we win and where we just claim to win

Never produce content that misrepresents a competitor. It's both wrong and
a litigation risk.

.claude/agents/[Link]
 ---
name: commercial-strategist
description: Commercial strategy specialist for deal structure, pricing scenarios, discount a
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: green
---

You are a senior commercial strategist. Your job is to structure deals

that close at terms the business can live with.

Your responsibilities:
1. Model pricing scenarios with clear assumptions
2. Identify commercial risks: term length, auto-renewal, ramp, indemnification, data rights
3. Recommend discount posture tied to strategic value, not just desperation
4. Flag terms that will block legal or finance approval downstream

When invoked:
- Read the account context, MEDDPICC or equivalent qualification, and deal parameters
- Produce scenarios in a structured table: price, term, commit, risks, upside
- Distinguish between concessions that cost us and ones that only feel expensive
- Never recommend terms outside stated approval authority without flagging it

Good commercial strategy means knowing which concession is cheap and which
is catastrophic. Name the difference every time.

.claude/agents/[Link]

---
name: proposal-writer
description: Proposal and client-facing content specialist for writing executive summaries, s
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: orange
---

You are a senior proposal writer. Your job is to produce client-facing

content that advances the deal without overcommitting the business.

Your responsibilities:
1. Write executive summaries that a C-level reader finishes in 90 seconds
2. Turn discovery findings into solution narratives the customer recognizes
3. Produce meeting recap emails that move the deal forward, not just summarize
4. Match tone to the stakeholder — never use marketing voice on a CFO

When invoked:
 - Read discovery notes, competitive context, and commercial parameters
- Mirror the customer's language from their own statements — not industry jargon
- Never promise a feature, timeline, or commercial term that hasn't been approved
- Every client-facing document has a specific next action it asks for

Ground every capability claim in something real. Customers remember

overpromises for years.

.claude/agents/[Link]

---
name: follow-up-orchestrator
description: Follow-up specialist for tracking open commitments, drafting next-step communica
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: cyan
memory: project
---

You are the deal's operational memory. Your job is to make sure nothing
falls through the cracks between milestones.

Your responsibilities:
1. Track every open commitment — ours and theirs — with dates and owners
2. Draft follow-up messages that land the commitments without nagging
3. Maintain stakeholder cadence: who we've talked to when, what's due next
4. Flag stalled threads before they become dead ones

When invoked:
- Read all prior communications and the current commitments list
- Update the commitments file; do not rewrite history
- Use your memory to track what follow-up tones work with which stakeholders
- Never send anything automatically — draft, present, and let the AE send

A deal dies from too many unanswered threads, not from a single bad meeting.

Part 5 — Best practices

Much of the tutorial has scattered best practices where they were relevant. This section
pulls them together and adds the ones that only become obvious after running a subagent
team for a few weeks.

Designing the team

 One subagent, one job. Resist consolidating. A “fullstack engineer” agent covers too
much scope to enforce standards meaningfully. Five narrow specialists beat two
generalists every time.

Write descriptions that route well. The description field is how Claude decides
when to delegate. “Use proactively when…” phrasing measurably improves automatic
routing. Specific triggers beat vague domains — “Use when reviewing copy for voice
consistency” routes better than “Handles copy tasks.”

Make boundaries explicit in both directions. When two agents might overlap, state
the boundary in both system prompts. The copywriter’s prompt says “never edit code.”
The component engineer’s prompt says “never modify content copy.” Redundant on
purpose.

Start with five. Adjust from there. Five specialists is enough to see the shape of your
work and expose real gaps. Don’t design the perfect eleven-agent team up front —
you’ll be wrong about three of them and only discover it by using the team.

Tool and permission hygiene

All of the fields below live in the YAML frontmatter at the top of each subagent file. See Part
3’s primer for the format itself and Step 8’s anatomy section for the specific field reference.

Grant the minimum tools needed. The copywriter doesn’t need Bash. The designer
doesn’t need Write access to src/ . A critic doesn’t need write access to anything.
Every unnecessary tool is a potential accident.

Use disallowedTools when inheritance is otherwise fine. If you want the agent to
inherit most tools but specifically block Write and Edit, that’s what disallowedTools is
for. Don’t rebuild the whole allowlist unnecessarily.

Prefer read-only for review agents. Critics, reviewers, and auditors should produce
observations, not edits. The separation of powers is the point — a reviewer that can
rewrite the thing it’s reviewing is no longer a reviewer.

Be deliberate about permissionMode . bypassPermissions skips approval prompts

entirely. Useful in automation, dangerous in interactive work unless you really mean it.

Context management
Keep [Link] tight. 200–400 lines is a good ceiling for most projects. Beyond that,
you’re loading noise into every subagent’s context. Move detailed docs into purpose-
specific files that agents read only when relevant.

Enable memory: project for learning agents. Engineers, analysts, discovery leads —
 anyone whose value compounds with context — should persist knowledge between
sessions. Designers and copywriters usually don’t need it if voice and tokens already live
in files.

Include memory instructions in the system prompt. Don’t just enable memory — tell
the agent what to record. “Update your memory with recurring patterns, codebase
decisions, and gotchas.” Without guidance, memory accumulates noise.

Never paste large files into the main conversation when a subagent could read
them. That defeats the whole point of context isolation.

Operating the team

Orchestrate from the main conversation, not inside a subagent. Subagents can’t
spawn other subagents. Chaining happens at the top level. If you find yourself wanting a
subagent to call another one, that’s a signal you need a different structure (or agent
teams).

Use @-mentions when automatic delegation misfires. If Claude keeps picking the
wrong specialist for a recurring task, either tighten the description or use @agent-name
to force the choice for that turn.

Use --agent for sustained focused work. When you’re spending a whole session on
one type of work (a copy sweep, a design review), run the session under that agent with
claude --agent copywriter . The main thread itself takes on the specialist’s scope.

Know when not to use subagents. For quick questions you want answered in-context,
use /btw . For tightly iterative work across phases, stay in the main conversation.
Subagents add overhead; don’t pay the overhead for trivial tasks.

Evolution
Treat .claude/agents/ as reviewed code. Changes to system prompts are changes to
how the project operates. Review them with the same seriousness as any other code
change.

When a subagent needs the same correction twice, update its prompt. That’s the
signal. Corrections in the moment are fine; corrections as a pattern mean the prompt is
wrong.

Review the team quarterly. Read each prompt cold. If you wouldn’t hire the described
employee, the prompt needs work.

Kill subagents that don’t earn their keep. More agents means more configuration to
maintain. If an agent is never invoked, delete it.
Part 6 — Git and multi-agent projects
The .claude/ folder is configuration, not output. It deserves the same version-control
discipline as the rest of your project. This section covers the patterns that scale as the team
and the agent team both grow.

Version the agent team itself

Treat every file in .claude/agents/ as a reviewed artifact.

Commit the entire .claude/ folder to your main branch. Unless you have specific
secrets in subagent configs (unusual), this is part of the project from day one.

Use descriptive commit messages for agent changes. “Update copywriter prompt” tells
you nothing six months later. “Copywriter: forbid superlatives after Q1 voice audit” tells
future-you exactly why the constraint exists.

Require review for agent prompt changes. Once more than one person works with the
project, changes to .claude/agents/*.md should go through PR review. These prompts
govern how Claude works with the codebase — they’re as consequential as CI config or a
linting rule.

Branching for prompt experimentation

When you want to try a new approach to an agent without disrupting the working team:

git checkout -b experiment/stricter-copywriter

# edit .claude/agents/[Link]
claude # test the new prompt in a session

If it works, merge to main. If it doesn’t, discard the branch. The agent reverts to its prior
behavior instantly because its prompt is a file, not a deployed service.

This is especially useful when iterating on the description field — Claude’s routing
behavior can shift subtly with small wording changes, and branches let you compare
behavior head-to-head.

Worktrees for parallel independent work

A git worktree is a second working copy of the same repository, checked out at a different
branch, in a different folder. Normal git gives you one working copy at a time; worktrees let
you have several.
Claude Code supports this directly. Any subagent can be configured to run in a temporary
worktree with one frontmatter field:

---
name: feature-engineer
description: Implements independent features in isolation
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
isolation: worktree
---

When this agent runs, Claude Code creates a temporary worktree, does its work there, and
cleans the worktree up automatically if the agent makes no changes. If the agent does make
changes, you get a branch you can review and merge.

When worktrees are genuinely useful:

Parallel independent implementation. Two feature branches that don’t interact — two
subagents, two worktrees, true isolation. No chance of one stomping the other’s files.

Experimental work. When you want an agent to try something speculative and have it
auto-disappear if it doesn’t pan out.

Testing agent prompt changes against your real codebase. Run the new prompt in a
worktree. If it behaves badly, nothing in your working tree is affected.

When worktrees are overkill:

Most sequential workflows (design → copy → implementation). The specialists work in

turn on the same files, which is the point.

Content-only or research-only projects. There’s no code to isolate.

Small projects where the orchestration overhead exceeds the task.

Honest assessment: for the majority of teams adopting subagents, worktrees are
unnecessary. The five-specialist pattern in this tutorial is designed around sequential
orchestration, where the specialists build on each other’s output. Worktrees solve a real
problem — parallel, genuinely independent work — but it’s a narrower problem than the
framing sometimes suggests. Add them when you hit the specific case. Don’t adopt them
preemptively.

Sharing teams across projects

If you run multiple projects with similar shapes (multiple websites, multiple research
engagements, multiple accounts), you’ll want to reuse subagent configurations rather than
rewriting them each time. Three patterns, in order of sophistication:

1. User-scope agents ( ~/.claude/agents/ ). Put your go-to specialists in the user-scope

folder. They’ll be available in every project on your machine. Best for agents that don’t
need project-specific tuning.

2. Template repository. On GitHub, create a repo that contains a fully configured

.claude/ folder plus a starter [Link] . Mark it as a template repo. New projects of
that shape are one click away from a full team.

3. Claude Code plugins. For reusable distribution across an organization, package the
agent team as a plugin. Plugins are versioned, installable, and can be shared across
teams without copy-paste.

Pick the simplest pattern that works. Many teams never need plugins — user-scope agents
and a template repo cover most of the ground.

The pull-request discipline for agents

A useful convention once the team is stable: require that any change to
.claude/agents/*.md include, in the PR description, a sentence about what behavior the
change is intended to cause or prevent. Prompts are hard to test. The stated intent is the
closest thing to a test you get.

Example:

Change: Copywriter now requires concrete numeric claims instead of adjectives. Intent:
After three pieces in a row containing “dramatically improved” with no supporting figures,
tighten the rule so the agent asks for the number instead of guessing one.

Six months later, that note is what lets someone (including future-you) decide whether the
rule still earns its place.

Part 7 — Maintenance

Keep [Link] current

If the stack changes, the directory structure changes, or the audience changes, update
[Link] that same day. Every subagent reads it. Stale context produces confident-but-
wrong output.

Know when to use agent teams instead

Subagents can’t spawn other subagents and work within a single session. If your workflow
truly needs multiple specialists running in parallel with their own sustained contexts, that’s
what agent teams are for. Subagents handle the majority of cases.

Reference
Official subagents documentation: [Link]

Claude Code overview: [Link]

[Link] and project memory: [Link]

Agent teams: [Link]

One last note for anyone coming from single-agent mode

The temptation with subagents is to think of them as employees you delegate to and forget.
They aren’t. Subagents are only as good as their system prompt and the context you give
them via [Link] . The work isn’t gone — it’s moved upstream, into designing the team
well.

The first time through feels like overhead. By your third project, you’ll wonder how you ever
worked without it.