A Deep Dive into Claude Code's New Custom Subagents Feature

Recently, Claude Code released a brand new feature called Custom Subagents, and we'll be going over that in this article and all the things you can do with it. The official documentation provides a comprehensive overview, and this article will serve as a practical guide, walking through the key aspects of the docs.

This new feature is a somewhat formalized approach to what people have been doing so far. For example, a while back, some users discovered you could spawn different subagents in parallel by instructing Claude Code accordingly. In reality, this just spawned different tasks in parallel. Other developers have been using an agents.md file in their codebase, coordinating multiple instances of Claude Code running in different terminals. The approach Claude Code has now implemented is somewhat different, offering a more structured and powerful way to manage specialized AI assistants.

Getting Started: Version Check

Before you begin, it's crucial to ensure you are on the right version of Claude Code. The version that includes this feature is 1.0.60, which notes the ability to create custom subagents for specialized tasks.

You can check your version by running: bash claude --version You should see the correct version, 1.0.60, displayed. Afterward, running claude and typing /agents should present the "manage agent configurations" option.

Understanding Subagent Capabilities

Anthropic describes these subagents as pre-configured AI personalities to which Claude Code can delegate tasks. Each subagent has its own specific purpose and area of expertise.

Here are some of their key characteristics: - Separate Context Window: Each subagent uses its own context window, separate from the main conversation. This is quite powerful, as it prevents performance degradation when the main conversation history becomes too long. - Configurable Tools: Subagents can be configured with a specific set of tools they are allowed to use. This is excellent for creating read-only agents, agents that can only perform web searches, or agents with other specific limitations. - Custom System Prompts: Each includes a custom system prompt that guides its behavior. - Task Delegation: When the main Claude Code thread encounters a task matching a subagent's expertise, it delegates the task to that subagent, which works independently and returns the results.

This design ensures that each subagent operates in its own context, preventing pollution of the main conversation. They can be fine-tuned with detailed instructions for higher success rates and can be reused across different projects and shared with your team, which is powerful for ensuring consistent rules and behavior on the same codebase.

Creating Your First Subagent

To get started, navigate to your codebase where Claude Code is running and type /agents. You will see the built-in general-purpose Claude Code agent and an option to create a new one.

1. Choose Scope: You can create an agent for the specific project (stored in .claude/agents) or a global agent for your entire system (stored in your home directory). For this example, we'll create a project-specific agent.
2. Generate with Claude: You can create an agent manually or generate one with Claude, which is the recommended approach. Anthropic suggests generating the initial subagent with Claude and then iterating on it. This provides a solid foundation that you can customize.
3. Describe the Subagent: Provide a description of what your subagent should do. For instance, let's create a performance analyzer: > "Performance analyzer subagent that looks through the codebase and finds areas for performance improvements."
4. Assign Tools: Next, decide which tools the agent can access. You can select from presets like read-only tools, edit tools, or execution tools, or you can view and select from all individual tools (task, bash, multi-edit, websearch, etc.). Since this agent should only analyze, we'll select read-only tools.
5. Choose a Color: A nice touch is the ability to assign a color to your agent. When multiple agents are running, each appears with a different color, which can be useful for tracking. Let's choose purple.
6. Review and Create: You'll be shown a preview of the agent file, including its description and system prompt. Once you confirm, the agent file is created in your project.

The generated file, performance-analyzer.agent.md, will contain the description, the list of available tools, the assigned color, and a detailed system prompt. You can refine this prompt later as you observe the agent's behavior. This file can be committed to your repository, allowing your team to use the same subagents.

Note: Project-specific subagents are given higher priority than user-level subagents if Claude Code determines that a task could be handled by either.

Managing and Invoking Subagents

If you type /agents again, you'll see the list of subagents available for the project. You can select one to view, edit, or delete it.

To explicitly invoke a subagent, use its name in your prompt: Use the performance analyzer subagent to suggest improvements to the project. Claude Code will confirm it's using the specified agent, which will then initialize (indicated by its color) and begin executing its tasks.

Best Practices for Effective Subagents

Anthropic provides several best practices for creating high-quality subagents:

• Use Claude-Generated Agents: Start with an agent generated by Claude and refine it to fit your needs.
• Design-Focused Subagents: It's better to have subagents with single, clear responsibilities rather than a single subagent that does everything. This improves predictability and performance.
• Write Detailed Prompts: Include specific instructions, examples, and constraints in your system prompts. The more guidance you provide, the better the subagent will perform.
• Limit Tool Access: Only grant the tools necessary for the subagent's purpose. This improves security and helps the subagent focus on relevant actions, as having too many tools can degrade performance.
• Version Control Your Subagents: Commit your .claude/agents directory to your repository so your team can benefit from and collaboratively improve them.

Advanced Usage: Chaining Subagents

One of the most powerful features is the ability to chain subagents together. Let's create a couple more subagents to demonstrate this.

1. Code Optimizer Subagent: An agent that "makes high-quality optimizations across a codebase whilst preserving intent." This agent would be given access to edit tools and execution tools.
2. Release Notes Subagent: An agent that "will write high-quality release notes based on the changes that were made since the last commit." This agent should be given read-only tools to prevent it from making unintended changes.

Once these agents are created, you can chain them in a single prompt:

Can you analyze the performance of the codebase, then make optimizations, and finally, write release notes for me in Markdown, all using subagents?

Initially, Claude Code might try to run these in parallel. If the tasks are sequential, you can clarify: "run them one by one."

The system will then execute the chain: 1. The Performance Analyzer runs first, identifying bottlenecks. 2. Its output is passed to the Code Optimizer, which then makes the necessary code changes. 3. Finally, the Release Notes Generator takes the context of the changes and composes the release notes.

It's quite impressive to see each subagent manage its own set of to-dos and pass the context seamlessly to the next one in the chain.

Potential Subagent Workflows

This feature opens up numerous possibilities for complex, automated workflows. Imagine a multi-agent system for software development:

• Spec Writer: A subagent that helps you write a detailed specification following established software design principles.
• Example Finder: Running in parallel, this agent could search the web for high-quality code examples from GitHub relevant to the spec.
• Doc Agent: An agent that finds up-to-date documentation for libraries and frameworks mentioned in the spec.
• Coding Agent: The primary agent responsible for writing the code based on the spec and examples.
• README Syncer: An agent that automatically updates the README.md file with any changes made by the coding agent.
• i18n Translator: For internationalized applications, a subagent could check for missing translation keys and automatically translate them.
• Social Media Post Writer: After a release, an agent could generate multiple draft posts for social media, written in a specific style.

The power of Claude Code extends beyond just coding. Many are using it to manage text files, edit documents in Obsidian, and perform other non-engineering tasks. The ability to create custom subagent workflows will only make it more powerful over time.

Future Outlook

Because this feature is very new, the community is just beginning to explore its potential. Over the next few weeks, we can expect to see many powerful subagents, system prompts, and workflows being shared. The ability to build, share, and chain these specialized AI assistants marks a significant step forward in AI-assisted development.