Subagent Generator

What a Claude Code subagent file actually is

A subagent is just a markdown file with YAML frontmatter at the top and a system prompt in the body. The frontmatter tells Claude Code what the agent is called, when to use it, which tools it may touch, and which model runs it. The body is the agent's instructions - its role, its process, and its guardrails. That is the entire format. This generator fills in the frontmatter correctly and gives you a solid prompt scaffold so the file loads and runs on the first try.

The reason people get subagents wrong is not the concept - it is the small details. A missing dash in the frontmatter, a description that never says when to invoke the agent, or a tools list with a typo will all quietly break delegation. Generating the file removes those failure modes.

The frontmatter fields, explained

• name - a short kebab-case identifier the main session uses to call the agent (for example, code-reviewer). This becomes the filename too.
• description - what the agent does and, critically, when to use it. This is the field Claude Code reads to decide whether to delegate a task, so make the 'when' explicit.
• tools - a comma-separated list of the tools this agent may use. Omit this field entirely and the agent inherits all tools; name them and it is restricted to exactly that list.
• model - opus, sonnet, or haiku to pin the model, or leave it out (or set inherit) to use the main session's model.

Why you should scope the tools

Leaving the tools field off is the convenient default, but it grants the agent every tool - including Edit, Write, and Bash. For a read-only role like a reviewer or a researcher, that is a liability: the agent can start changing things it was never meant to touch. Naming the tools explicitly keeps a specialist a specialist. As a rule, give read-only roles Read, Grep, and Glob; give building roles Read, Edit, Write, and Bash; and add WebFetch only when the agent genuinely needs the internet.

Writing the system prompt body

1. State the single responsibility in one sentence. An agent that does one thing well beats one that does five things adequately.
2. Give it a short numbered process - what to read first, what to do, and how to report back. This keeps behavior consistent across invocations.
3. Add guardrails: what it must not do, and what to do when something is ambiguous. 'State your assumption instead of guessing silently' prevents a whole class of quiet failures.
4. Specify the output format if the caller depends on it. A reviewer that returns a bullet list of required changes is more useful than one that writes prose.
5. Keep it tight. The body is loaded every time the agent runs, so every extra paragraph is a recurring token cost.

Project agents vs personal agents

Save the file to .claude/agents/ inside your repo to make it a project agent - it is committed with the code and shared with your whole team, so everyone gets the same reviewer or tester. Save it to ~/.claude/agents/ to make it a personal agent that follows you across every project. When a project agent and a personal agent share a name, the project one wins. For anything the team relies on, prefer the project location so the behavior is version-controlled.

How the main session uses it

Once the file exists, the main Claude Code session can delegate to the agent by name - either automatically, when the task matches the description, or explicitly when you ask it to use that agent. The subagent runs in its own fresh context with only its allowed tools, does the scoped work, and returns a result. Because its context is separate, it does not pollute your main session with intermediate noise, which is a large part of why subagents improve reliability on long tasks.

Common mistakes this generator prevents

• Frontmatter that is not valid YAML - a missing dash line or a stray colon that stops the file loading.
• A description that never says when to invoke the agent, so the main session never delegates to it.
• An over-permissioned agent that inherits Bash and Write when it only needed to read.
• A name with spaces or capitals that does not match the expected kebab-case identifier.
• A bloated system prompt that costs tokens on every run without improving behavior.