Claude Code Subagents Quick Reference

Table of Contents

• Locations and scope
• Loading and reload behavior
• Frontmatter fields
• Tools and permissions
• Skills and hooks
• Delegation patterns

Locations and Scope

• Project subagents: .claude/agents/
• User subagents: ~/.claude/agents/
• Session subagents: CLI --agents JSON with project and user paths

Claude Code loads project subagents before user subagents. Session configuration can override by pointing to specific directories.

Example session config:

claude --agents '{"project":".claude/agents","user":"~/.claude/agents"}'

Loading and Reload Behavior

Subagents are loaded when a session starts. After adding or editing a subagent, reload them (restart or use /agents).

Frontmatter Fields

Required:

• name: Unique identifier for routing and invocation.
• description: Routing hint that explains when to use the subagent.

Optional:

• tools: List allowed tools. Omit to allow all tools, or set [] for no tools.
• disallowedTools: Denylist to block specific tools.
• model: Model override if supported in your Claude Code setup.
• permissionMode: Permission handling mode for tool use.
• skills: Skill names to preload for this subagent.
• hooks: Hook list to run during execution.
• disabled: Set true to disable without deleting.
• color: Display color for terminal visibility (cyan, blue, green, magenta, yellow, red, white).

Tools and Permissions

Permission modes:

• default: Ask for confirmation when required.
• acceptEdits: Auto-accept file edits but still ask for shell commands.
• dontAsk: Auto-deny tool use.
• bypassPermissions: Skip permission prompts (use only in trusted setups).
• plan: Always plan before tool use.

Skills and Hooks

• skills preloads skill content for the subagent and is not inherited from the parent.
• hooks can automate setup steps but should be used sparingly and documented.

System Prompt Note

Subagents only receive their own system prompt, not the full Claude Code system prompt. Include all required constraints in the subagent file.

Delegation Patterns

• Use subagents for verbose or specialized tasks to keep the main context clean.
• Use the main agent for interactive, iterative work.
• Subagents cannot spawn other subagents; coordinate delegation from the main agent.