Most "AI agent team" advice describes a fleet of chatbots with job titles. A researcher agent, a writer agent, a reviewer agent, each with a personality paragraph. I have built and run agent teams on my own production Laravel site for months, and the setups that actually finish work look nothing like that. A working agent team is one orchestrator, disposable workers, and a strict filesystem contract between them. The personalities are irrelevant. The contract is everything.
This post walks through how I structure agent teams in Claude Code using subagents, MCP servers, and Skills, based on the pipelines I run against this site's codebase and content. Not a thought experiment: the largest of these runs rewrote 84 blog posts across 7 batches, with resumable state, per-row backups, and a verification gate, while I mostly reviewed outputs.
What an agent team actually is in Claude Code
Claude Code gives you three building blocks, and it pays to be precise about what each one does:
Subagents are separate Claude instances your main session can spawn for a scoped task. They get their own context window, do their work, and return a result. This is the "team" part. The main session becomes an orchestrator; the subagents are workers.
MCP servers (Model Context Protocol) connect agents to real systems. In my setup the workhorse is Laravel Boost, an MCP server that gives agents direct access to my application's routes, database schema, config, logs, and a tinker execution surface. A worker that can query the real schema does not hallucinate column names. I wrote up the Laravel Boost MCP setup separately if you run Laravel.
Skills are packaged instruction sets an agent loads on demand for a specific kind of task: a review checklist, a deploy procedure, a writing standard. They are how you make judgment repeatable across workers instead of re-explaining it in every prompt. I have built enough of these that I now maintain a marketplace of 53 agent skills covering my recurring workflows.
The mistake most first-time builders make is treating these as three flavors of the same thing. They are not. Subagents give you parallelism, MCP gives you ground truth, Skills give you consistency. A team missing any one of the three fails in a predictable way: without subagents you have a bottleneck, without MCP you have confident fabrication, without Skills you have quality drift between workers.
A real run, end to end
Here is the shape of an actual pipeline I ran on this site, because concrete beats abstract.
The task: rewrite dozens of blog posts to a specific editorial and SEO standard. Too much for one context window, too repetitive for me, too risky to let a single agent free-run against a production database.
The orchestrator was my main Claude Code session. It read an index of all posts, planned batches of roughly a dozen, and dispatched one worker per batch.
Each worker received the same brief: the post IDs, the quality rubric, and three non-negotiable invariants. First, back up the current row to a JSON file before drafting anything. Second, write output as local markdown files only, never touch the database. Third, return results through a structured output schema (post ID, status, self-assessed rubric scores) rather than prose.
The state layer was a manifest file, REWRITE-STATUS.json, tracking every post as DONE or PENDING. Workers do not update it; a small script does, after verification. Because the manifest lives on disk, any future session can resume the pipeline cold. When a session died mid-batch, and one did, I lost nothing but that batch's drafts.
The gate was a verify script that checked hard constraints on every output file (links resolve, no forbidden patterns, frontmatter intact) before anything got applied. Apply was a separate, single-purpose script with a range guard so a typo could not touch rows outside the batch.
Seven batches later: 84 posts rewritten, every original recoverable from backups, and a status file that let me answer "where are we?" in one cat.
The insight that changed how I build these
Subagents do not share memory. Each worker starts blank. Early on I fought this by stuffing more and more context into dispatch prompts, and the results got worse, not better, because long prompts bury the invariants.
The fix is to stop treating context as something you pass and start treating the filesystem as the team's shared memory. Workers read their inputs from files (reports/posts-index.json, the rubric, the manifest) and write their outputs to files (rewrites/*.md, backups/*.json). The files are the API between agents. The dispatch prompt shrinks to: here is your assignment, here are the file paths, here is the contract.
This has a second-order benefit nobody mentions: the pipeline becomes inspectable. When a worker produces a weak output, I do not interrogate a chat log. I open its files, see exactly what it read and wrote, and fix the contract. Debugging an agent team through transcripts is archaeology. Debugging it through artifacts is engineering.
Rules that keep a team from hurting you
These are all scar tissue, not theory.
Workers never write to production. Read access, yes; my workers SELECT from the live database freely. But every mutation flows through one reviewed apply step with backups already on disk. The one time you skip this is the one time a worker misreads an ID range.
Backup before draft, always. A backup step that happens "at the end" is a backup that a crashed session never wrote. Make it the worker's first action and make the orchestrator check for the file's existence.
Structured outputs, not prose reports. A worker that returns "I finished the batch successfully!" has told you nothing machine-checkable. A worker that returns JSON with per-item status can be diffed against the manifest automatically. Ambiguity between agents compounds faster than between people.
Scope roles by artifact, not by topic. "The SEO agent" is a vague role that overlaps with everything. "The worker that produces rewrites/<id>.md files passing verify.py" is a role a machine can hold. If two agents could plausibly own the same file, your boundaries are wrong.
Keep workers disposable. If a worker fails, you should be able to kill it and dispatch a fresh one with the same assignment. That only works when state lives in files instead of in the worker's context. Disposability is the property that makes parallelism safe; if you want to run workers against the same repo simultaneously, git worktrees are the missing piece.
Where MCP fits, and where it does not
MCP earns its place when an agent needs ground truth mid-task: the actual database schema, the actual route list, live application logs. During my batch runs, workers used database access to fetch current post content rather than trusting a possibly stale export, and that alone prevented a class of overwrite bugs.
But MCP servers are also the easiest way to bloat a team. Every server you attach costs context and adds tools the model must reason about. My rule now: the orchestrator gets the MCP servers, workers get only what their contract requires, and most workers need nothing beyond file access. If you are deciding which servers deserve a slot at all, I keep a shortlist in my must-have MCPs post.
Where Skills fit
Skills carry the judgment that prompts lose. My rewrite workers all applied the same quality rubric because the rubric lived in one place and every worker loaded it, not because I pasted it seven times and hoped. The same pattern covers my review checklists and deploy procedures.
The test for whether something should become a skill: have I explained this to an agent three times? Then it is a skill. The mechanics of writing one are simpler than people expect, and the agent skills guide covers the format.
Start with two agents, not five
The minimum viable agent team is an orchestrator and one worker with a file contract between them. Build that first:
- Pick a batchable task you already understand deeply. Content processing, test generation, data cleanup.
- Define the worker's contract: input files, output files, invariants, output schema.
- Run one batch. Read every artifact the worker produced, not just the summary.
- Add the verify gate before you add the second worker.
- Only then scale out, and scale workers before you scale roles.
Teams amplify whatever process exists. If your single-agent workflow produces sloppy output, five agents will produce sloppy output faster. The boring artifacts, manifests, backups, verify scripts, are not overhead on the real work. On a team of agents, they are the real work. The supporting cast of terminal tooling matters too; the CLI tools I use daily are mostly there to audit what workers did.
The orchestration skills on my agent skills marketplace encode the contracts this post described — assignment format, verify step, backup rule — in a form your own Claude Code sessions can load today. Take those first; write your own once you know which contract your team keeps breaking.
