Create Claude Code Subagents with /agents

Claude Code does not have a /subagent-create command. Subagents are created and managed with the built-in /agents command, by writing a Markdown file with YAML frontmatter under .claude/agents/ or ~/.claude/agents/, or by passing the --agents flag at launch. This entry documents the real workflow.

What a subagent is

A subagent is a specialized assistant that runs in its own context window with a custom system prompt, its own tool access, and independent permissions. When a task matches a subagent's description, Claude can delegate to it; the subagent works independently and returns only its result, keeping verbose output (logs, search results, file dumps) out of your main conversation.

Claude Code also ships built-in subagents that it uses automatically: Explore (fast, read-only codebase search on Haiku), Plan (read-only research during plan mode), and general-purpose (full tools for multi-step work).

The /agents command (recommended)

Run /agents in an interactive session to open a tabbed interface:

/agents

• Running tab: lists live and recently finished subagents; open or stop them.
• Library tab: view all available subagents (built-in, project, user, plugin), create new ones with guided setup or "Generate with Claude", edit configuration and tool access, and delete custom subagents.

Creating one through /agents walks you through: choosing a scope (Personal ~/.claude/agents/ or Project .claude/agents/), generating or writing the name/description/system prompt, selecting which tools it may use, picking a model, choosing a display color, and optionally enabling persistent memory. Subagents created through /agents take effect immediately, with no restart.

This is a built-in Claude Code command. There are no flags like --code-reviewer, --tools=, --parallel=, --status, or --list — those are not part of Claude Code.

Subagent definition files

A subagent is a Markdown file with YAML frontmatter followed by the system prompt body. Store it by scope:

Example .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Expert code review specialist. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Provide feedback by priority: Critical issues, Warnings, Suggestions.
Include specific examples of how to fix each issue.

If you edit a file on disk directly, restart the session to load it. (Files created through /agents load immediately.)

Supported frontmatter fields

Only name and description are required. Real fields from the documentation include:

• name — unique lowercase-hyphen identifier (the filename need not match).
• description — when Claude should delegate to this subagent.
• tools — allowlist of tools (inherits all if omitted).
• disallowedTools — denylist removed from the inherited/specified set.
• model — sonnet, opus, haiku, fable, a full model ID (e.g. claude-opus-4-8), or inherit (default).
• permissionMode — default, acceptEdits, auto, dontAsk, bypassPermissions, or plan.
• skills — Skills to preload into the subagent's context.
• mcpServers — MCP servers scoped to this subagent.
• hooks — lifecycle hooks scoped to the subagent.
• memory — persistent memory scope: user, project, or local.
• maxTurns, effort, background, isolation (worktree), color, initialPrompt.

Scoping tools (least privilege)

Restrict capability with tools (allowlist) or disallowedTools (denylist). A read-only researcher:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

If both fields are set, disallowedTools is applied first, then tools resolves against what remains. A tool listed in both is removed.

Session-scoped subagents via CLI

Define ephemeral subagents (not saved to disk) when launching:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Run an entire session as one subagent with claude --agent code-reviewer (its system prompt, tools, and model replace the defaults for the main thread).

Invoking subagents

• Automatic delegation: Claude reads each subagent's description and the task to decide when to delegate. Add "use proactively" to the description to encourage it.
• Natural language: "Use the code-reviewer subagent to look at my recent changes."
• @-mention: type @ and pick the subagent (e.g. @agent-code-reviewer) to guarantee that subagent runs for the task.

When to use this

Reach for a subagent when a side task produces verbose output you do not need in the main context, when you want to enforce specific tool restrictions, or when self-contained work can return just a summary. For reusable prompts that run in the main context instead of an isolated one, consider Skills.

• Source repositorygithub.com 2026-07-13T15:19:32-07:00
• Documentationcode.claude.com