| name | claude-subagent-creator |
| description | 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). |
| license | MIT |
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.
