Claude Code's Sub-Agents Explained in 5 Minutes

Anthropic has released a powerful new feature in Claude Code: Sub-Agents. Let's explore what they are and how you can use them.

What Are Sub-Agents?

In our daily work as developers, we often wear multiple hats. One moment we're acting as a product manager, the next we're writing automation scripts, reviewing designs, or coding a new feature. A sub-agent is Claude Code's way of letting you define each of these distinct roles as a specialized AI assistant.

Configuration Options

So, what can you configure for a sub-agent? There are several key aspects:

• Purpose: A clear purpose and a defined area of expertise.
• Tools: A specific set of tools it can use, including MCPs (Multi-Component Processes).
• System Prompt: A custom system prompt to guide its behavior and tone.

You can set up these sub-agents on a per-project basis or make them available globally across all your projects.

Pricing and Access

Currently, the sub-agents feature is available to all Claude Code users with a Pro or Max subscription. The exact token usage is still being evaluated, but it's something to monitor as you integrate them into your workflow.

Creating Your First Sub-Agent: A Step-by-Step Guide

Ready to create your first sub-agent? It's a straightforward process.

1. Initiate the Command: Start by using the /aents command in the terminal. If you don't see this command, you may need to update to the latest version of Claude Code.

2. Choose Configuration Scope: You'll be asked whether to configure the agent for the current project or globally. For this example, we'll select the project-specific option.

3. Select Generation Method: You have two main ways to generate a sub-agent: automatically with Claude or manually. We'll start with the "Generate with Claude" option to see how it works.

4. Describe the Agent's Role: Let's create a sub-agent designed for writing automations. Provide a clear description, such as:

   Expert automation writer that handles all levels of tests: unit, integration, and end-to-end.

5. Configure Tools: Next, you need to configure the tools the agent can access. While you can select everything by default, it is highly recommended to manually select only the necessary tools. This prevents the agent from performing unexpected actions or damaging your repository. You can define permissions for:

   • Read-only tools
   • Editing tools
   • Execution tools
   • MCPs and other specialized tools

   For our automation expert, we want it to have access to the Playwright MCP. You will need to select each function within the MCP individually.

6. Choose an Identifier: Finally, you can pick a color to visually identify the agent.

That's it! The sub-agent is now created.

Manual Configuration

If you opt for a manual setup, you'll find the configuration file located in your project's hidden .cloud folder, specifically under agents/. For our example, the file would be named test-automation-expert.md.

Inside this file, you can see all the attributes that need to be configured: * name * description * context_prompt * Any other context attached to the agent.

Reviewing a file generated by Claude is a great way to understand all the attributes required for a manual setup.

Running a Sub-Agent

To use your newly created sub-agent, simply mention it within a prompt to Claude. For instance:

@Test Automation Expert, please review my end-to-end tests.

When the sub-agent is active, you will see its designated color in the interface, indicating that it is processing your request.

Sub-agents are a powerful addition to Claude Code, allowing for more specialized and efficient workflows. As the tool becomes more intelligent, however, it may also become more expensive in terms of token usage, so it's wise to be mindful of your consumption.