create-subagent

Create subagents by defining a system prompt, name, and description, then store them as files under .claude/agents/ or dispatch them dynamically via the Task tool. Subagents isolate context and apply tailored configurations like tools, model selection, and permissions to handle focused work independently.

File-based subagents persist under .claude/agents/ with stored system prompts for repeatable workflows. Task tool subagents are dynamic, created on-demand during execution with inline prompts. Choose file-based for stable roles; use Task tool for one-off specialized tasks requiring isolated context.

Use subagents when tasks require specialized expertise, need isolated context to avoid interference, must follow repeatable workflows, or benefit from differentiated tool permissions. They prevent context pollution and enable parallel or sequential delegation with role-specific constraints.

Name and description are required for all subagents. Optional fields include tools (which capabilities the subagent accesses), model (inference model), permissionMode (access controls), and skills (pre-built task patterns). Templates for common roles like code-reviewer and tester provide configuration starting points.

Yes. Subagent configuration supports per-agent tool selection, permission modes, and skill assignment, allowing you to restrict access and tailor capabilities to the task. This prevents unnecessary tool exposure and enforces role-based workflows within delegated work.