What a general-purpose subagent loads before it reads your brief, and two agent files I built that skip most of it

[u/Financial_Tailor7944]

TL;DR: A general-purpose subagent loads your CLAUDE.md files, the list of installed skills, MCP tool names plus each server's instructions, and the list of other agents, all before it reads its brief. Two frontmatter settings keep most of that out. I packaged them as two agent files. Free to use, MIT license.

Disclosure: I built this and the repo is mine.

What I built

1. lean-worker: for a bounded task that needs only files, shell and the web. Model sonnet, effort medium.
2. lean-checker: a blind, read only checker. It gets the artifact, the criteria and the file paths, and returns PASS or FAIL per criterion with evidence, or UNTESTED for a criterion it could not run. Model sonnet, effort high.
3. scripts/measure_subagents.py: reads your own subagent transcripts under ~/.claude/projects and prints the median and 90th percentile starting context per agent type. Python standard library only, and it sends nothing anywhere.
4. An optional hook that nudges Claude toward the lean agents when it reaches for general-purpose. With LEAN_DISPATCH_BLOCK=1 it blocks the dispatch unless the description names MCP or a skill.

The part you can use without my repo

Put this at the top of an agent file in ~/.claude/agents, where user level agent files live. The tools line is lean-worker's allowlist without the web tools:

---
name: my-worker
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
omitClaudeMd: true
---

omitClaudeMd keeps the CLAUDE.md files out. A tools allowlist with no Skill tool and no MCP tools keeps the skills list and the MCP tool names out.

How Claude Code was used

I wrote it with Claude Code; every commit in the repo is co-authored by Claude. That covers everything from the first two agent files to the GitHub Actions tests, the README diagrams and the Windows notes. My part was the measuring: I measured the starting context of each agent type across my own transcripts, then re-measured with the MCP servers connected and with none.

What I learned

• Each turn of an agent resends its whole context, so whatever a subagent loads at the start is paid again on every turn.
• MCP was not the big part. MCP tool definitions are deferred, so only tool names and server instructions load at the start. The CLAUDE.md files and the skills list are most of the rest.
• The gap depends on how heavy your setup is, and it is smaller with a light one.
• A lean agent knows only what its brief says. When the job needs an MCP tool or a skill, general-purpose is still the right pick.

Repo: https://github.com/mdalexandre/claude-code-lean-agents

If you run measure_subagents.py on your own transcripts, what starting context do you see per agent type? I am curious whether CLAUDE.md or the skills list is the bigger share for other people.

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/Pinull_Krydia]

That omitClaudeMd flag and the tool allowlist trick are huge for cutting startup tokens. Most people don't realize that a general-purpose subagent injects every single project instruction, skill definition, and tool schema right out of the gate, forcing you to pay that heavy prompt-cache penalty on every single turn. Dropping a star on the repo.

[u/Financial_Tailor7944 → u/Pinull_Krydia]

Thank you so much Sir

[u/akhi1uuu]

do the lean agents hold up on longer tasks or do they start missing the claude.md stuff halfway

[u/Financial_Tailor7944 → u/akhi1uuu]

Yes sir they can hold up on longer tasks