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: >-4 Author, validate, and install custom Claude Code subagents as .claude/agents Markdown files. Use5 when the user asks to create a subagent, custom agent, or .claude/agents role; define a reusable6 reviewer, explorer, planner, or worker persona; set an agent's model or tool allowlist; or turn a7 recurring workflow into a delegatable role. Produces Markdown agent files with YAML frontmatter8 (name, description, model, tools) plus a focused system-prompt body, scoped to the smallest tool9 surface that does the job (read-only by default). Covers naming, description wording for autonomous10 delegation, model policy (Opus for reasoning/review, inherit for scans), tool scoping, project vs11 user scope, and a smoke test. Pairs with fan-out, which delegates to these roles. Not for one-off12 ad-hoc delegation (use fan-out) or authoring Agent Skills (SKILL.md files).13license: MIT14---1516# Claude subagent creator1718Create well-scoped custom subagents Claude Code can auto-delegate to. A subagent is a Markdown file19with YAML frontmatter plus a system-prompt body; it runs in its own context window with its own tool20surface.2122## When to use2324- The user wants a reusable persona (reviewer, explorer, planner, scoped worker).25- A workflow recurs often enough to deserve a named role `fan-out` can target.26- You need to pin a model or restrict tools for a class of delegated work.2728For a one-off delegation, don't author a file — just use `fan-out`'s inline spawn contract.2930## Agent file anatomy3132`./.claude/agents/<name>.md` (project) or `~/.claude/agents/<name>.md` (user):3334```markdown35---36name: <hyphen-case, matches filename>37description: <what it does + WHEN to delegate to it — explicit triggers; this drives auto-selection>38model: opus # or sonnet / haiku / omit to inherit the session model39tools: Read, Grep, Glob, Bash # smallest surface that works; omit = inherit all40---41<system prompt: role, exact scope, output contract, hard boundaries>42```4344## Authoring workflow45461. **Name + intent** — hyphen-case name; one clear job. Avoid catch-alls.472. **Description for delegation** — lead with the action, then `Use when ...` with concrete triggers48 ("Use when reviewing a diff for security issues"). The main agent matches this to decide delegation;49 vague descriptions don't get auto-selected.503. **Model policy** — `opus` for reasoning/review/debugging/planning; `sonnet`/`haiku` or inherit for51 read-heavy scans and inventories. Omit `model:` to inherit the session model.524. **Tool scoping** — grant the minimum. Default **read-only** (`Read, Grep, Glob, Bash`); add53 `Edit, Write` only for workers that own a disjoint write surface.545. **System prompt** — state the role, the exact scope, the return contract (status, evidence with55 file:line, commands run, findings + confidence, risks), and hard boundaries ("never edit outside56 your assigned files"; "you inherit no parent transcript — work only from this prompt").576. **Install + smoke test** — write the file, then confirm via `/agents` (or the Task tool with58 `subagent_type: <name>`) that it loads and a trivial scoped task returns the contracted shape.5960## Description-for-delegation rules6162- Action verb first; then explicit "Use when" triggers and the keywords a request would contain.63- Name the boundary ("read-only", "does not commit") so the parent scopes it correctly.64- One responsibility per agent — overlapping agents compete and dilute auto-selection.6566## Scope6768- **Project** (`./.claude/agents/`) — committed, shared with the repo, available in that project.69- **User** (`~/.claude/agents/`) — personal, available across all your projects.70- Project agents shadow user agents of the same name.7172## Failure modes7374| Symptom | Fix |75|---|---|76| Agent never auto-delegated | weak description — add explicit "Use when" + trigger keywords |77| Agent over-reaches / edits too much | tighten `tools:` and the scope line in the body |78| Inconsistent results | pin `model: opus`; specify an exact return contract |79| Two agents fight over the same work | merge or sharpen responsibilities; one job each |80| Worker reverted another's edits | enforce disjoint write surfaces; read-only by default |8182Use `fan-out` to delegate to the roles you create here.
BjornMelin