Claude Code Subagents: The Config, Two We Run, and What 161 Public Agents Show

What is a Claude Code subagent, and which ones are built in?

The subagents documentation, read on 26 September 2026, defines them in one line: “Subagents are specialized AI assistants that handle specific types of tasks.” The sentence that matters for cost and behaviour follows: “Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. It also sends its own requests, which count toward the same usage limits as your main conversation.” Two consequences fall out of that. Whatever the subagent reads never enters your conversation, only its report does. And the tokens it burns are yours.

Six subagents ship with the CLI. The docs describe them as follows, and the two you will see most are the read-only pair:

Delegation happens four ways per the docs: Claude picks a subagent from its description automatically, you @-mention one, you name it in plain language (“use the test-runner subagent to fix failing tests”), or you start a whole session as one with claude --agent name. The description field is therefore doing two jobs, which the measurement section comes back to.

How do you define a subagent?

One markdown file. The frontmatter configures it; the body becomes its system prompt. The docs' own example, verbatim:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Where the file lives sets its scope, and the docs list five locations in priority order, highest first: managed settings for an organisation, the --agents CLI flag for one session, .claude/agents/ in the project, ~/.claude/agents/ for all your projects, and a plugin's agents directory. The docs' advice on the project folder: “Check them into version control so your team can use and improve them collaboratively.” Files added on disk load at the next session start; ones created through /agents take effect immediately.

Two fields are required and sixteen are optional. The full list from the docs, grouped by what each one controls:

The last box is the one to design around. The docs list what does not reach a subagent: your conversation history, skills already invoked, files Claude has already read, and the main session's auto memory. A subagent knows only what its file and its task message tell it. If it needs the schema, the task message names the file. If it needs a house rule, the rule is in the body. Our Claude Code commands guide covers the skills that can be preloaded through the skills field.

What do 161 public subagents actually look like?

The largest public collection is VoltAgent/awesome-claude-code-subagents, 25,335 stars, last pushed 2026-09-21, which ships an install script that copies its agents into your folder. We cloned it on 26 September 2026 and measured every definition with frontmatter: 161 files in ten categories.

The collection gets the tool restriction right and the description budget mostly right: installing all 161 would spend about 57% of the threshold the docs warn at, on every session start, before you type anything. The docs' fix is the one to apply before installing anything from a collection: “Trim the description fields of your subagents, and move detail into each subagent's system prompt, which only loads when that subagent runs.” The body lengths, a median of 281 lines with almost no variance, point to a generated template; read one before trusting it with edit permissions.

Which subagents do we run, and what did the first run find?

Two, both checked into this site's repository under .claude/agents/ on 26 September 2026, both read-only, both built for the guide workflow this page came out of. They exist because the work they do floods a conversation with output nobody needs to read twice: a list of HTTP statuses and a list of rule violations.

---
name: source-checker
description: Fetches every external URL cited on one /learn guide and reports HTTP status and the final URL after redirects. Use before publishing or refreshing a guide.
tools: Bash, Read, Grep
model: sonnet
---
You check citations for lovable-prompts.com guides. You are given one page file under src/app/learn/.

1. Read the file and collect every external href (http or https, not lovable-prompts.com), including URLs held in constants.
2. Fetch each once with `curl -sL -o /dev/null -m 20 -w "%{http_code} %{url_effective}"`.
3. Report one table: URL, status, final URL, note. Flag anything that is not 200 and anything whose final URL has a different path from the cited one.
4. Do not edit files. Keep the report under 40 lines.

We ran the source-checker prompt against the Cursor rules guide, published an hour earlier, on 26 September 2026. Because a file added on disk only loads at the next session start, the run used a general-purpose subagent on the same model with the file body as its task. The harness reported the cost; the subagent timed itself with date +%s at start and end.

The finding was correct and we had missed it: Cursor moved its rules page and the citation we published pointed at the old path. The guide now cites the new one. That is the whole case for this class of subagent in 112,045 tokens: a check we would not have run by hand on a page we had just finished, with a report short enough to act on. The tokens are not small. The same eight curl calls in the main session would have cost a fraction of that, in exchange for eight blocks of output in the conversation and no summary. The trade is context for tokens.

---
name: guide-reviewer
description: Reviews one /learn guide against the house content rules and reports violations with line numbers. Use after drafting a guide and before the build gates.
tools: Read, Grep, Bash
model: sonnet
---
You review guides for lovable-prompts.com. You are given one page file under src/app/learn/.

Check, and report each finding as `line: rule: quote`:
- Banned words anywhere in prose: em dash, land, lands, landed, real (except real-time), delve, leverage, robust, unlock, navigate, elevate.
- Every number in prose has a source named in the same or the previous sentence, or comes from an imported data file.
- Every external quotation is inside quotation marks and names its source page.
- Every H2 is a question, and the first sentence under it answers it.
- No affiliate URL pasted as a literal; Lovable CTAs go through lovableAffiliateUrl().
- Dates: any "checked on" or "read on" date is today's date or earlier.

Do not edit the file. End with a count of findings by rule.

The reviewer encodes the rules every guide on this site is held to, including the banned-word list and the one-question-per-heading structure. It is the same list as the grep gate in the build, with judgement added for the rules grep cannot check, such as whether a number has a source in the same sentence.

When should a task be a subagent, a skill, or the main session?

Anthropic's own guidance is in How and when to use subagents in Claude Code on the Claude blog (7 April 2026), and it gives a threshold: “When a task requires exploring ten or more files, or involves three or more independent pieces of work, that's a strong signal to delegate Claude toward subagents.” The same post names the counter-case: “When step two needs the full output of step one, and step three needs both, a single session handling the chain is usually cleaner than a relay of subagents passing state through files.”

The three reasons the blog gives for delegating are research (“a subagent can explore the codebase and return a summary rather than dumping dozens of files into the conversation”), parallel independent work, and a fresh perspective for review because a subagent “doesn't inherit the assumptions, context, or blind spots from the primary conversation”. Our two subagents are the first and third kind. A migration written in three files where each depends on the previous one is the second case and stays in the main session, as does anything you want to watch happen, which is what the advanced prompting guide covers on the Lovable side with Plan mode and chains.

Does Lovable have subagents?

Yes, inside Plan mode, and they are the reason a plan is not a flat one credit. Lovable's Plan mode documentation says: “For larger or open-ended requests, Lovable can start subagents to research your project before it writes the plan”, and “A Plan mode message costs one credit, plus the cost of any subagents Lovable starts to research your project while planning, so a message that needs deep research costs more than one credit.” You cannot define them, restrict their tools or pick their model; the docs' one lever is “Keep planning requests specific and point them at particular files, features, or areas. Broad requests are more likely to need subagent research.”

The design is the same as Claude Code's Explore agent with the configuration removed: research runs outside the main thread and only the plan comes back. What differs is the bill. Claude Code counts a subagent's requests against your usage limits; Lovable meters it in credits on top of the message. The Lovable credits guide has the measured burn per prompt type, and the Lovable vs Cursor page covers what an export gains when it moves to a tool where the agents are yours to configure.

Sources

All checked on 26 September 2026. Corpus numbers and the run log are in src/data/claudeCodeSubagents.ts in the site repository; the two subagent files are in .claude/agents/.

• Claude Code docs: Create custom subagents
• Claude blog: How and when to use subagents in Claude Code (7 April 2026)
• Lovable docs: Plan a change in Plan mode
• GitHub: VoltAgent/awesome-claude-code-subagents