Claude subagent creator
Create well-scoped custom subagents Claude Code can auto-delegate to. A subagent is a Markdown file
with YAML frontmatter plus a system-prompt body; it runs in its own context window with its own tool
surface.
When to use
- The user wants a reusable persona (reviewer, explorer, planner, scoped worker).
- A workflow recurs often enough to deserve a named role
fan-out can target.
- You need to pin a model or restrict tools for a class of delegated work.
For a one-off delegation, don't author a file — just use fan-out's inline spawn contract.
Agent file anatomy
./.claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (user):
---
name: <hyphen-case, matches filename>
description: <what it does + WHEN to delegate to it — explicit triggers; this drives auto-selection>
model: opus # or sonnet / haiku / omit to inherit the session model
tools: Read, Grep, Glob, Bash # smallest surface that works; omit = inherit all
---
<system prompt: role, exact scope, output contract, hard boundaries>
Authoring workflow
- Name + intent — hyphen-case name; one clear job. Avoid catch-alls.
- Description for delegation — lead with the action, then
Use when ... with concrete triggers
("Use when reviewing a diff for security issues"). The main agent matches this to decide delegation;
vague descriptions don't get auto-selected.
- Model policy —
opus for reasoning/review/debugging/planning; sonnet/haiku or inherit for
read-heavy scans and inventories. Omit model: to inherit the session model.
- Tool scoping — grant the minimum. Default read-only (
Read, Grep, Glob, Bash); add
Edit, Write only for workers that own a disjoint write surface.
- System prompt — state the role, the exact scope, the return contract (status, evidence with
file:line, commands run, findings + confidence, risks), and hard boundaries ("never edit outside
your assigned files"; "you inherit no parent transcript — work only from this prompt").
- Install + smoke test — write the file, then confirm via
/agents (or the Task tool with
subagent_type: <name>) that it loads and a trivial scoped task returns the contracted shape.
Description-for-delegation rules
- Action verb first; then explicit "Use when" triggers and the keywords a request would contain.
- Name the boundary ("read-only", "does not commit") so the parent scopes it correctly.
- One responsibility per agent — overlapping agents compete and dilute auto-selection.
Scope
- Project (
./.claude/agents/) — committed, shared with the repo, available in that project.
- User (
~/.claude/agents/) — personal, available across all your projects.
- Project agents shadow user agents of the same name.
Failure modes
| Symptom |
Fix |
| Agent never auto-delegated |
weak description — add explicit "Use when" + trigger keywords |
| Agent over-reaches / edits too much |
tighten tools: and the scope line in the body |
| Inconsistent results |
pin model: opus; specify an exact return contract |
| Two agents fight over the same work |
merge or sharpen responsibilities; one job each |
| Worker reverted another's edits |
enforce disjoint write surfaces; read-only by default |
Use fan-out to delegate to the roles you create here.
1---2name: claude-subagent-creator3description: Author, validate, and install custom Claude Code subagents as .claude/agents Markdown files. Use when the user asks to create a subagent, custom agent, or .claude/agents role; define a reusable reviewer, explorer, planner, or worker persona; set an agent's model or tool allowlist; or turn a recurring workflow into a delegatable role. Produces Markdown agent files with YAML frontmatter (name, description, model, tools) plus a focused system-prompt body, scoped to the smallest tool surface that does the job (read-only by default). Covers naming, description wording for autonomous delegation, model policy (Opus for reasoning/review, inherit for scans), tool scoping, project vs user scope, and a smoke test. Pairs with fan-out, which delegates to these roles. Not for one-off ad-hoc delegation (use fan-out) or authoring Agent Skills (SKILL.md files).4license: MIT5---67# Claude subagent creator89Create well-scoped custom subagents Claude Code can auto-delegate to. A subagent is a Markdown file10with YAML frontmatter plus a system-prompt body; it runs in its own context window with its own tool11surface.1213## When to use1415- The user wants a reusable persona (reviewer, explorer, planner, scoped worker).16- A workflow recurs often enough to deserve a named role `fan-out` can target.17- You need to pin a model or restrict tools for a class of delegated work.1819For a one-off delegation, don't author a file — just use `fan-out`'s inline spawn contract.2021## Agent file anatomy2223`./.claude/agents/<name>.md` (project) or `~/.claude/agents/<name>.md` (user):2425```markdown26---27name: <hyphen-case, matches filename>28description: <what it does + WHEN to delegate to it — explicit triggers; this drives auto-selection>29model: opus # or sonnet / haiku / omit to inherit the session model30tools: Read, Grep, Glob, Bash # smallest surface that works; omit = inherit all31---32<system prompt: role, exact scope, output contract, hard boundaries>33```3435## Authoring workflow36371. **Name + intent** — hyphen-case name; one clear job. Avoid catch-alls.382. **Description for delegation** — lead with the action, then `Use when ...` with concrete triggers39 ("Use when reviewing a diff for security issues"). The main agent matches this to decide delegation;40 vague descriptions don't get auto-selected.413. **Model policy** — `opus` for reasoning/review/debugging/planning; `sonnet`/`haiku` or inherit for42 read-heavy scans and inventories. Omit `model:` to inherit the session model.434. **Tool scoping** — grant the minimum. Default **read-only** (`Read, Grep, Glob, Bash`); add44 `Edit, Write` only for workers that own a disjoint write surface.455. **System prompt** — state the role, the exact scope, the return contract (status, evidence with46 file:line, commands run, findings + confidence, risks), and hard boundaries ("never edit outside47 your assigned files"; "you inherit no parent transcript — work only from this prompt").486. **Install + smoke test** — write the file, then confirm via `/agents` (or the Task tool with49 `subagent_type: <name>`) that it loads and a trivial scoped task returns the contracted shape.5051## Description-for-delegation rules5253- Action verb first; then explicit "Use when" triggers and the keywords a request would contain.54- Name the boundary ("read-only", "does not commit") so the parent scopes it correctly.55- One responsibility per agent — overlapping agents compete and dilute auto-selection.5657## Scope5859- **Project** (`./.claude/agents/`) — committed, shared with the repo, available in that project.60- **User** (`~/.claude/agents/`) — personal, available across all your projects.61- Project agents shadow user agents of the same name.6263## Failure modes6465| Symptom | Fix |66|---|---|67| Agent never auto-delegated | weak description — add explicit "Use when" + trigger keywords |68| Agent over-reaches / edits too much | tighten `tools:` and the scope line in the body |69| Inconsistent results | pin `model: opus`; specify an exact return contract |70| Two agents fight over the same work | merge or sharpen responsibilities; one job each |71| Worker reverted another's edits | enforce disjoint write surfaces; read-only by default |7273Use `fan-out` to delegate to the roles you create here.
BjornMelin