Subagents in Claude Code

We've already seen how Claude Code can supercharge your development workflow. In this topic, we'll see how you can go even further by adding subagents.

What are subagents?

A subagent is a pre-configured assistant personality with its own system prompt, allowed tool list, and separate context window. They are like small, specialized teams that perform specific tasks you define. You can let Claude Code automatically delegate to subagents or call them by name as needed.

Subagents are role-specific helpers that you define once and reuse across tasks and projects. They improve your daily work because they:

• Preserve context — Each subagent works in its own context, preventing deep dives from cluttering your main thread.

• Increase focus and quality — Narrow, role-specific prompts typically perform better than a single general prompt.

• Promote reuse — You can store shared project subagents in version control and keep personal subagents that follow you across projects.

Each subagent can be configured with different tools and access levels, which improves security. For subagents to behave consistently, you can document norms in CLAUDE.md.

Creating subagents

You can create subagents from the interactive REPL and follow the guided flow:

/agents

Then, select "Create new agent". Next, you'll need to pick a scope for the agent. The subagents configuration is stored as Markdown files with YAML front matter in one of the following locations:

• Project scope: .claude/agents/ — highest precedence

• Personal scope: ~/.claude/agents/ — lower precedence

Choose a scope and proceed to the next step. You'll be prompted to select a creation method. You can choose "Generate with Claude" to scaffold the initial template that you can customize later. In the next step, write a suitable description for the agent. The description determines when the subagent should be called, so make sure it is actionable and appropriate for the best results. Also, aim for one responsibility per subagent rather than giving a single subagent multiple responsibilities.

Next, choose the tools available to the subagent. Here, it's best to give the subagent access to only the tools and permissions that it needs to perform its task, following the principle of least privilege. If omitted, the subagent inherits the main thread's tools. Next, select the model for the subagent to use. Finally, choose a color for the subagent, and save:

---
name: slack-issue-resolver
description: Use PROACTIVELY whenever Slack messages indicate technical problems or requests for code changes
tools: *
model: inherit
---

You are a Senior DevOps and Full-Stack Engineer who rapidly identifies, analyzes, and resolves technical issues from Slack reports.

When invoked:
1. Parse and analyze the report — extract key details, errors, and affected systems.
2. Investigate thoroughly — review logs, configs, and recent changes to isolate root causes.
3. Develop solutions — propose clear fixes (quick vs. comprehensive), including code, config, or deployment steps.
4. Communicate clearly — summarize issues, explain fixes in plain language, and provide implementation steps.
5. Follow best practices — prioritize by severity, document assumptions, and recommend monitoring improvements.

You're done when:
- Issue details are fully understood (error, context, impact)
- Relevant logs, code, and configs reviewed
- Root cause clearly identified
- Solution targets cause, not symptoms
- Proposed fix tested or test steps provided
- Rollback or mitigation plan considered
- No disruption to other systems or environments
- Explanation clear and accessible to non-technical stakeholders
- Assumptions, risks, and follow-up actions documented

Your responses should be concise, technically rigorous, and easy to follow—combining deep expertise with clear, actionable communication.

You can manually create subagents by defining Markdown files with this structure and saving them in the appropriate directory. If you need to edit the agent configuration, just type /agents, select the agent, and choose Edit agent in the list of options. You can also delete subagents in the same way.

Using subagents

Claude Code can select a subagent automatically based on your request, the subagent's description, current context, and available tools:

Action-oriented descriptions like “You MUST USE...” can improve the likelihood that a certain subagent will be selected. Alternatively, you can request that a specific subagent be used by its name:

Use the slack-issue-resolver subagent to investigate and fix the latest Slack issue. 

You can even chain multiple subagents when the work benefits from a pipeline:

First use the slack-investigator subagent to collect issue details, then use the slack-reporter subagent to post comments in Slack.

Conclusion

Subagents make Claude Code modular: each specialist has a clear job, their own context, and the right tools. Create agents with /agents, giving each an appropriate, action-oriented description and only the tools it requires. Finally, let Claude Code automatically choose the appropriate subagent to use, explicitly invoke the needed subagent, or even chain multiple subagents depending on the workflow.