I built my first custom subagent around the autumn of 2025. At the time, I had just started running six websites in parallel — four technical blogs and two long-form sites — and I was looking for any way to stop being the only person bouncing between repositories every single day.
Six months later, the lineup of custom subagents inside .claude/agents/ had shrunk from five to two. Pruning, rather than adding, turned out to be the direction I drifted in. I want to write down what happened along the way.
I'm Masaki Hirokawa (Dolice), an indie developer who has been shipping apps since 2014.
The First Three Months: Believing More Subagents Was Better
For the first three months, I added one whenever I thought of one.
- An SEO audit subagent for articles
- A subagent that wrote release notes from repository diffs
- A subagent that compared schedule task configurations across four sites and flagged inconsistencies
- A subagent that read older articles and suggested rewrite candidates
- A subagent that read AdMob eCPM reports and proposed mediation orderings
When I opened .claude/agents/, there were five files, some of which I couldn't even remember creating.
It sounded reasonable on paper — "I have a small team of specialists on call." In practice, none of it ran as cleanly as I had imagined. The subagent's output wasn't as good as I expected, or it was faster to do the work directly in the main session. That gap built up slowly over the first three months.
Survivor #1: The "Just Go Read" Explore-Style Subagent
The first one that survived is the one that does nothing but read. It's a lightly tuned version of the Explore role that comes with Cowork out of the box.
The reason this one worked was clear. The wider the surface area it has to read, the more I benefit from not polluting the main context. My workspace has six site repositories, operational documents, SEO data, and SKILL.md files scattered around. When I want to trace something like "which subagent wrote this article" or "which document is the source of truth for AdMob priority settings," reading everything in the main session burns context fast. Asking a dedicated Explore-style subagent to go wide, read shallow, and only bring back a report keeps the main side moving.
The thing I learned over six months is that I had to fix the prompt to this subagent into a very simple shape: "You may read anything you need to in order to answer the following question, but report back in 300 characters or less." That was it. Narrowing both the role and the exit shape made it actually useful.
Survivor #2: The "Design Review" Plan-Style Subagent
The second survivor is the one I call during design — to borrow a pair of eyes that isn't mine.
One of the hardest parts of working solo is that I rarely get to show a design to another person. The experience behind 50 million cumulative app downloads since 2014 is real, but that same experience is also where my blind spots come from. It's hard to notice my own habits.
I gave this subagent a single role: "Given my design proposal, point out up to three angles I'm likely to have missed." Not suggestions. Angles. I don't ask it to write anything — I ask it to shine a light on what I've overlooked.
The implementation trick was to cleanly separate it from the main conversation. If I drop a design proposal into the main chat, my own assumptions leak into the framing and the subagent ends up seeing things through my eyes. I deliberately strip context away before handing the document to the subagent, so it reads the proposal as a first-time reader.
It looks like a detour, but six months in, this is what fits me.
The Three I Threw Out: Why They Didn't Work
Now the honest part — the three that didn't survive.
The first was the SEO audit subagent. The structural problem was that the audit report that came back still had to be read by me in the main session before I could act on it. A subagent isn't worth the split if the main session can't trust the conclusion and move on. That principle came from this one.
The second was the release notes generator. It could write release notes well enough, but the actual judgment — "what counts as part of this release" — required context about the whole site that only the main session was holding. I kept rewriting the output, which meant the split was costing more than it saved. Tasks where the scope decision can't be separated belong in Plan Mode, not in a subagent.
The third was the AdMob mediation order proposer. I dropped this one for a different reason. Combining the AdMob dashboard with Claude in Chrome turned out to fit my real workflow better than wrapping it inside a single subagent. From that one I drew a rule for myself: before building a new subagent, try the Chrome-integration path first and see if that's enough.
What I Learned About Writing the description
Lining the survivors and the dropouts up next to each other, the dividing line was the description field.
The descriptions on the survivors all wrote when to call them, not what they do. The three I dropped described the role — "an expert in X" or "produces a report on Y" — but didn't say when the main session should reach for them. From the main session's point of view, a subagent without a calling occasion is one that doesn't get called.
Here's roughly what the surviving Explore-style subagent's description looks like:
Use when you need to investigate facts that span multiple repositories,
documents, or SKILL.md files without burning main-session context.
Report back as a summary of 300 characters or less, never as full text.
Writing the negative condition ("never as full text") was the key. It lets the main session decide whether to call this subagent without hesitating.
One Tool, Used Well
Both of my grandfathers were temple carpenters. They didn't keep adding new tools — they sharpened the few they had, every day. The same plane, sharpened every morning, finished the wood with a surface only that plane could leave.
Six months of running custom subagents pointed me toward the same direction. Adding new ones wasn't paying back as much as maintaining the two I had. Against the reality of running six sites, that was the choice that worked.
What's Next
In the near term, I'm planning to add a small logging mechanism to each of the two remaining subagents that records the days they weren't called. A subagent that goes uncalled for a stretch is a signal to revisit its description, not a signal that it has earned its place.
If you're starting with custom subagents, I'd recommend building exactly one and running it for three weeks. If, after those three weeks, there were at least three moments where you genuinely felt "I'm glad I called this one," it's a keeper. If not, the right place to start is rewriting one line of its description.
I'm still in the middle of figuring this out myself. I hope the notes help.