Claude Code agents: how to set up subagents that earn their keep.

I run four brands on a crew of Claude Code agents. Not a metaphorical crew, an actual folder of markdown files with names, jobs and opinions about how my Stripe account should look. This guide is everything I wish someone had handed me before I built them: what subagents are, how the file model works, how to write one that pulls its weight, and the mistake that wastes most people’s first fortnight.

What a subagent actually is

Claude Code is Anthropic’s terminal-based coding agent. Out of the box it’s one very capable generalist. A subagent is a separate, named worker you define yourself: it gets its own system prompt, its own context window, and, if you want, its own restricted set of tools. When the main session hits a task that matches a subagent’s brief, it hands the work over. The subagent does the job in its own context and only the result comes back.

That last part matters more than it sounds. The subagent’s rummaging (the forty files it opened, the dead ends, the false starts) stays in its own context. Your main session receives the conclusion, not the mess. On a long working day that’s the difference between a sharp session and one drowning in its own history by lunchtime.

Agents are files. That’s the whole model.

There is no dashboard, no drag-and-drop builder, no “workforce portal”. A subagent is a markdown file in .claude/agents/ inside your project, or in ~/.claude/agents/if you want it available everywhere. The file has two parts. Frontmatter at the top: the agent’s name, a description that tells Claude Code when to hand work to it, and optionally which tools it may touch. Then everything below the frontmatter is the system prompt: who this agent is, what it does, how it reports back.

That’s it. Version-controlled, diffable, sackable with a single rm. When people ask why I like this model, that’s the answer: my “employees” are text files I can read in full. Try that with a human hire.

How to write a definition that works

Every good agent I’ve written follows three rules, and every bad one broke at least one of them.

One job.“Reconciles Stripe payouts and flags anything that doesn’t tie out” is a job. “Helps with finance stuff” is a horoscope. If you can’t state the job in one sentence with a verb in it, the agent will do a vague impression of usefulness and you’ll quietly stop calling it.

Clear inputs and outputs. Spell out what the agent receives and what it hands back, in what format. My finance agent returns a table with the same columns every night. Because the shape is fixed I can skim it in ten seconds, and I notice instantly when something is off. An agent that returns freeform prose every time is an agent whose output nobody reads by week three.

Honest limits.Write down what the agent must not do. Mine are told which directories they may touch, what they escalate instead of deciding, and when to say “this is outside my brief” rather than improvise. An agent without stated limits doesn’t become powerful. It becomes confidently wrong in new places.

A skeleton I actually use:

---
name: finance-recon
description: Nightly Stripe reconciliation across all
  brands. Use for payout, fee and refund questions.
tools: Read, Bash
---
You reconcile Stripe payouts for four brands.
[the job, in one sentence]
[inputs: what you read, and from where]
[output: the exact table format, every time]
[limits: what you never touch, what you escalate]

The mistake everyone makes

You will be tempted to create ten agents on day one. A marketing agent, a strategy agent, a “growth” agent, an agent whose job description is essentially vibes. I did exactly this. It felt like building a company. It performed like a costume party.

Vague agents fail quietly. They don’t error, they produce plausible mush, and because there are ten of them you can’t tell which one is earning anything. The fix is boring and it works: three sharp agents beat ten vague ones, every single time. Start with the one task you already do repeatedly that has a checkable output. Get that agent so good you trust it. Then add the second. My crew is twelve agents now, but it was one agent for a month, and that month is why the other eleven work.

How memory between sessions actually works

The bit nobody tells you up front: subagents start cold. Every session, every hand-off, blank slate. The agent file gives them their brief and their personality, but nothing they learned yesterday survives on its own.

Persistence is something you build, and it’s less grand than it sounds. Claude Code reads CLAUDE.mdfiles automatically at the start of a session, so standing knowledge about your business belongs there. Beyond that, the pattern that works is agents writing to files: a directory of structured markdown notes that agents update as they work and read back on their next run. My crew shares one, we call it the brain vault, and it’s the single biggest reason the crew gets sharper over months instead of having the same amnesiac Monday forever.

It is also, genuinely, the hard part. Deciding what gets remembered, in what structure, so twelve agents can rely on it without tripping over each other, took me longer than writing all twelve agent files combined. If you take one thing from this guide, take this: an agent’s intelligence comes from the model, but its usefulness comes from its memory. Budget your effort accordingly.

Roll your own, or start from a working crew?

You can absolutely build this yourself. Everything above is the honest map, and building your own crew teaches you things no download can. Roll your own if you have a spare fortnight, enjoy the tinkering, and your needs are unusual enough that nobody’s template fits.

A pre-built crew makes sense when the shape of the work is common (finance, content, ops, research: the jobs most small operators need are not exotic) and your scarce resource is time rather than money. What you’re paying for isn’t the markdown. It’s the decisions: the job boundaries, the output formats, the memory structure, and all the versions that didn’t work.

That’s what Crewibleis: the crew we run our own four brands with, packaged. Twelve specialists, the shared memory structure included, reskinnable to your business. If you’d rather start from something that has already survived contact with a real company, it’s here. And if you’d rather build your own, honestly, go well. This guide is most of the map.