Claude Code Subagent Generator

A subagent is a specialist Claude instance that runs in its own separate context window with a different system prompt, so you can delegate a well-defined subtask to it and get back only the summary. It is defined by a single markdown file at .claude/agents/<name>.md: YAML frontmatter with a name and a description on top, and a body that becomes that subagent's complete system prompt. Because it works in an isolated context, the long, messy exploration it does - reading fifty files, running greps, chasing dead ends - never lands in your main conversation. Only its final report does. That isolation is the whole point: it keeps your primary context clean, and it lets you give a narrow, dangerous-if-misused job a narrow set of tools.

A skill loads instructions into the conversation you are already having; a subagent starts a new conversation of its own. When a skill fires, its SKILL.md body is added to Claude's current context and Claude keeps working as itself, with everything it already knew. When a subagent fires, Claude spawns a separate instance with a blank context and a different system prompt, that instance works alone, and only its final message comes back. So reach for a skill when you want to teach Claude how to do something it will then do here - a house style, a checklist, a release procedure. Reach for a subagent when you want work done elsewhere and only want the conclusion: a big search you do not want cluttering your context, or a review you want performed by something that literally cannot edit your files. They also compose - a subagent can preload skills through its skills frontmatter field. A slash command is a third, simpler thing again: a saved prompt you fire by typing /name, run inline, with no isolation and no separate identity.

Create the folder with mkdir -p .claude/agents, save a markdown file in it named after the subagent, and reload Claude Code. The file needs YAML frontmatter with at least name (lowercase letters and hyphens only, no colons, unique) and description (when Claude should delegate to it), followed by the body that acts as its system prompt. Put it at .claude/agents/ inside the repo to commit it to git and share it with your team, or at ~/.claude/agents/ in your home folder to keep it personal across every project on your machine. If both exist with the same name, the project one wins inside that repo. This generator writes the whole file for you and shows the exact path and mkdir command for whichever scope you pick.

name and description are required. Optional fields include tools (a comma-separated allowlist of the tools this subagent may use, such as Read, Glob, Grep - omit it entirely and the subagent inherits every tool available), disallowedTools (the denylist counterpart), model (sonnet, opus, haiku, fable, a full model ID, or inherit to use whatever the main conversation is using), permissionMode (default, acceptEdits, auto, dontAsk, bypassPermissions or plan), maxTurns (a cap on how many agentic turns it may take before it stops and returns partial output), skills (a list of skill names preloaded into its context) and color (red, blue, green, yellow, purple, orange, pink or cyan, for display only). Rarer advanced fields also exist - mcpServers, hooks, memory, background, effort, isolation, initialPrompt and experimental.cacheTtl among them. This claude subagent yaml generator deliberately does not emit those: writing a field whose behaviour it cannot describe accurately would be worse than leaving it out, so add them by hand if you need them.

Because it is the only hard limit on what a subagent can do. Leave tools out and the subagent inherits everything the main conversation has, including MCP tools - fine for a trusted helper, needlessly risky for one whose entire job is to look and report. A security reviewer given Read, Glob, Grep physically cannot modify your working tree; the same reviewer with Bash and Write can. The rule of thumb is least privilege: grant the minimum that does the job, add Write and Edit only for a subagent that is supposed to change files, and add Bash only when it genuinely has to run something like a test suite. This builder flags the mismatch both ways - a review-shaped description holding write tools, and a fix-shaped description with no way to write anything.

It matches the task against each subagent's description, so that string is your routing table. A description like 'Reviews code' gives Claude nothing to discriminate on and will either be picked for everything or nothing. Name the concrete triggers instead: 'Reviews changed code for security vulnerabilities - injection, missing authorisation, unsafe deserialization, leaked secrets. Use proactively after any change to auth or input handling, and whenever the user asks for a security review.' Saying 'use proactively' encourages automatic delegation; you can always override by asking for one by name - 'use the security-code-reviewer subagent to check this diff'. In a claude code multi-agent setup where several subagents overlap, the descriptions need to draw clear borders between them, which is why this generator warns live when yours reads generically or drops the when half.

Write it in the second person, addressed to the subagent, and treat it as a complete briefing rather than a note. It replaces Claude Code's default system prompt entirely and starts with a blank context, so it should establish who the subagent is, the ordered steps it works through, the hard rules and things it must never do, and - crucially - what its final report must contain. That last part is easy to forget and it is what makes a subagent useful or useless: the main conversation sees nothing but that final message, so it needs to be self-contained, name absolute file paths, and not refer to 'the file above' or anything else the reader never saw.