Subagent

A subagent is a specialized assistant that handles a specific type of task in its own context-window, with a custom system prompt, specific tool access, and independent permissions. Use one when a side task would flood your main conversation with search results, logs, or file contents you will not reference again; the subagent handles that work in its own context and returns only the summary. Claude uses each subagent's description field to decide when to delegate.

Subagents are defined in .agent.md files. Verified locations for these files are .claude/agents/ (for the current project, checked into version control) and ~/.claude/agents/ (for all your projects). Claude Code scans both directories recursively. The identity of a subagent comes solely from its name frontmatter field, which must be unique, lowercase, and hyphen-separated; the filename or subfolder path does not contribute to its identity.

Required frontmatter fields include name and description. The description tells Claude when to delegate tasks to this subagent. Optionally, you can specify tools to grant access to specific tools (omitting this field grants access to all available tools). The model field can specify which Claude model to use (e.g., sonnet, opus, haiku, fable, or a full model ID) or inherit the default. A skills field can be used to preload specific skills into the subagent's context.

Plugin subagents do not support hooks, mcpServers, or permissionMode for security reasons. Claude Code monitors both agent directories, so edits to subagent definitions are applied within seconds without requiring a restart. The /agents command no longer opens a creation wizard; it prompts the user to ask Claude or edit the .agent.md files directly.

Skills like Sub-Agents can spawn external CLI AIs as scoped subagents, while Create Custom Agent scaffolds these .agent.md files. For complex workflows, Multi-Agent Coordinator can split tasks among subagents, and Agent Orchestration Advisor helps design these multi-agent systems, potentially leveraging progressive-disclosure patterns.