--- title: "Create a Subagent in Claude Code for Faster, Cleaner Workflows" description: "Learn how to create a subagent in Claude Code with this step-by-step guide covering setup, frontmatter, custom instructions, and practical examples." url: https://srinimf.com/2026/07/07/how-to-create-a-subagent-in-claude-code-a-step-by-step-guide/ date: 2026-07-07 modified: 2026-10-10 author: "Srini" image: https://i0.wp.com/srinimf.com/wp-content/uploads/2026/07/pexels-photo-37911158.jpeg?fit=1040%2C1300&ssl=1 categories: ["Artificial Intelligence"] tags: ["Anthropic", "Automation", "Claude Code", "Sub Agent"] type: post lang: en --- # Create a Subagent in Claude Code for Faster, Cleaner Workflows When you create a subagent in Claude Code, you spin up a specialized [Claude instance](https://docs.anthropic.com/en/docs/claude-code/overview) with its own context window, custom system prompt, and specific tool access — ideal for focused tasks like code review, testing, or research that might otherwise clutter your main conversation. ## Steps to Create a Subagent in Claude Code **Option A — Ask Claude to write it for you (recommended)** 1. In a Claude Code session, describe the subagent you want, e.g.:*“Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements for readability, performance, and best practices. Make it read-only and have it use Sonnet.”* 2. Claude will generate the Markdown file with the right frontmatter (name, description, tools, model) and system prompt. 3. Open the file it created and tweak anything you’d like. > Note: as of Claude Code v2.1.198+, the old `/agents` interactive wizard was removed. Running `/agents` now just reminds you to ask Claude directly or edit the files yourself — but the file format and locations are unchanged. **Option B — Write the file manually** 1. Create a Markdown file in one of these locations: - `.claude/agents/your-agent-name.md` → project-level (shared with your team via the repo) - `~/.claude/agents/your-agent-name.md` → personal, available across all your projects 2. Add YAML frontmatter + a system prompt body. Example: markdown ```markdown ---name: code-reviewerdescription: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.tools: Read, Grep, Glob, Bashmodel: sonnet---You are a senior code reviewer. When invoked:1. Run `git diff` to identify modified files.2. Focus review on changed code paths.3. List security issues, likely false positives, and suggested fixes.4. Provide a short, prioritized action list. ``` 1. Re[start your](https://srinimf.com/2012/02/06/start-your-mentoring-relationship-right/) Claude Code session — subagent files are loaded only at startup, so edits on disk won’t take effect until you restart. (Agents created via asking Claude in a live session take effect immediately.) ## Key Frontmatter Fields for Subagents | Field | Purpose | | --- | --- | | `name` | Unique identifier | | `description` | **This is what triggers delegation** — Claude matches tasks against it, so write it as a clear condition for use (e.g. “Use PROACTIVELY after writing code”) | | `tools` | Restrict which tools the subagent can access (e.g. `Read, Grep, Glob` for a read-only reviewer) | | `model` | `sonnet`, `opus`, `haiku`, or `inherit` (uses parent’s model) | ### Using Your Claude Code Subagent - Let Claude auto-delegate based on the `description` matching your request, or - Invoke explicitly: `claude -p "Use the code-reviewer [subagent](https://docs.anthropic.com/en/docs/claude-code/sub-agents) to review payment.py"` [Claude Code](https://docs.anthropic.com/en/docs/claude-code/cli-reference) also ships with built-in subagents (**Explore**, **Plan**, **general-purpose**) that it uses automatically without you needing to configure anything. ## Conclusion: Using Claude Code Subagents Subagents are one of the most practical upgrades you can make to your Claude Code workflow. By delegating token-heavy, repetitive, or specialized tasks — like code review, testing, or codebase exploration — to a dedicated subagent, you keep your main conversation focused and your context window clean. Getting started is simple: describe what you want to Claude and let it generate the subagent for you, or hand-write a Markdown file with the right YAML frontmatter in `.claude/agents/` or `~/.claude/agents/`. From there, it’s just a matter of refining the `description` field so Claude knows exactly when to delegate, and restricting `tools` and `model` choices to match the task at hand. For deeper dives into implementation patterns, check out our [e-books](https://srinimf.com/e-books/). ## Frequently Asked Questions About Claude Code Subagents ### What is a subagent in Claude Code? A subagent is a specialized Claude instance you configure with its own system prompt, tool access, and optional model choice. It runs in a separate context window, letting you delegate focused tasks — like code review, testing, or research — without cluttering your main conversation. ### Where are subagent files stored? Subagent definition files are Markdown files stored in one of two locations: `.claude/agents/` inside your project directory (shared with your team via the repository) or `~/.claude/agents/` in your home directory (personal agents available across all projects). ### How do you invoke a subagent explicitly? You can invoke a specific agent by name using the `-p` flag: `claude -p "Use the code-reviewer subagent to review payment.py"`. Alternatively, Claude will auto-delegate to the right agent based on your request matching the agent’s `description` field — no explicit invocation needed. ### Can subagents use tools? Yes. You define which tools a subagent can access using the `tools` frontmatter field. For example, a read-only reviewer might be limited to `Read, Grep, Glob`, while a more capable agent could also include `Bash` or `Write`. Restricting tools is a good way to enforce safe, predictable behavior. ## [How to](https://srinimf.com/2025/06/28/how-to-begin-coding-in-python-a-simple-action-plan/) Create a Subagent in Claude Code 1. **Choose a focused task.** Pick one repetitive or specialized workflow — such as code review, test generation, or documentation — that benefits from a dedicated context and toolset. 2. **Create the Markdown file.** Add a `.md` file to `.claude/agents/` (project-level, shared with your team) or `~/.claude/agents/` (personal, available across all projects). Use a clear, hyphenated filename like `code-reviewer.md`. 3. **Add YAML frontmatter and a system prompt.** At the top of the file, include `name`, `description` (written as a clear trigger condition), `tools`, and optionally `model`. Below the frontmatter delimiter (`---`), write the agent’s instructions in plain language. 4. **Restart or reload Claude Code.** Agents defined in files are loaded at session startup, so restart your session for the new agent [to become a](https://srinimf.com/2015/03/08/am-i-too-old-to-become-a-computer-programmer/)vailable. Agents created by asking Claude directly take effect immediately without a restart. 5. **Test and refine.** Ask Claude to use the agent or trigger it automatically via its description. If the behavior isn’t quite right, adjust the system prompt, tighten the `description` trigger, or change the allowed tools, then restart and test again. Start small — one or two subagents for your most repetitive tasks — and expand as you find more workflows worth isolating. Once you experience how much cleaner and faster your sessions become, it’s hard to go back to a single generalist agent handling everything. [Learn more](https://srinimf.com/about/) about advanced Claude Code techniques. [Home](https://srinimf.com/) ### Share this: - - [Tweet](https://twitter.com/share) - [![](https://i0.wp.com/assets.pinterest.com/images/pidgets/pinit_fg_en_rect_gray_20.png)](https://www.pinterest.com/pin/create/link/?url=https%3A%2F%2Fsrinimf.com%2F2026%2F07%2F07%2Fhow-to-create-a-subagent-in-claude-code-a-step-by-step-guide%2F&media=https%3A%2F%2Fi0.wp.com%2Fsrinimf.com%2Fwp-content%2Fuploads%2F2026%2F07%2Fpexels-photo-37911158.jpeg%3Ffit%3D960%252C1200%26ssl%3D1&description=Create%20a%20Subagent%20in%20Claude%20Code%20for%20Faster%2C%20Cleaner%20Workflows) - - [Share on Tumblr](https://www.tumblr.com/share) - [Share on WhatsApp (Opens in new window) WhatsApp](https://srinimf.com/2026/07/07/how-to-create-a-subagent-in-claude-code-a-step-by-step-guide/?share=jetpack-whatsapp) - [More](#) - - [Print (Opens in new window) Print](https://srinimf.com/2026/07/07/how-to-create-a-subagent-in-claude-code-a-step-by-step-guide/?share=print) - [Share on Reddit (Opens in new window) Reddit](https://srinimf.com/2026/07/07/how-to-create-a-subagent-in-claude-code-a-step-by-step-guide/?share=reddit) - [Share on Telegram (Opens in new window) Telegram](https://srinimf.com/2026/07/07/how-to-create-a-subagent-in-claude-code-a-step-by-step-guide/?share=telegram) - [Email a link to a friend (Opens in new window) Email](mailto:?subject=%5BShared%20Post%5D%20Create%20a%20Subagent%20in%20Claude%20Code%20for%20Faster%2C%20Cleaner%20Workflows&body=https%3A%2F%2Fsrinimf.com%2F2026%2F07%2F07%2Fhow-to-create-a-subagent-in-claude-code-a-step-by-step-guide%2F&share=email) - ### Like this: Like Loading…