Unlocking AI Superpowers: A Guide to Claude Code's Custom Sub-Agents

Claude Code has recently introduced custom sub-agents, and I've already created one to assist in selecting the optimal tech stack for my upcoming projects. These sub-agents can be tailored to be as specific or as broad as necessary, and the most significant advantage is their complete customizability.

What Are These Sub-Agents and Why Are They So Helpful?

You have likely observed numerous individuals developing functionalities similar to an agent directly within Claude. I have previously adapted others' concepts to build a mini-agent using custom slash commands that could generate any number of UI iterations. However, Claude now provides the capability to create customized agents within Claude Code itself by using the /agents command.

Key Benefits of Sub-Agents

According to Anthropic, the main benefits are clear and powerful:

• Specific Purpose and Expertise: Each agent is designed with a specific purpose and area of expertise. This is quite similar to creating a custom GPT in ChatGPT, where you can assign a unique persona and a specific job to an agent, which it then executes with focus.
• Separate Context Window: An agent utilizes its own context window, distinct from the main conversation. This is incredibly useful as it allows for a side conversation with the custom agent on various topics like user interface, testing, design, or even marketing and product definition. Any topic you can imagine can be explored without cluttering the context of the main project.
• Configurable Tool Access: You can customize these agents by going through a checklist of tools they are permitted to use. This includes MCP servers, and you can specify a broader range of permissions, such as read-only access or full control.
• Reusability: The definition for a sub-agent resides in a markdown file within the .claude directory, which can be placed at either the user or project level. Because these sub-agents are defined in a file, you can easily check this file into a repository, move it between projects, or customize it as needed.

Creating a Custom Tech Stack Advisor

For my first sub-agent, I identified the need for a tech stack advisor. My knowledge of front-end development is limited, and my back-end development expertise is somewhat outdated. There is a great deal I don't know, and even more that I am unaware I don't know.

So, I instructed Claude Code to create a new agent with the following persona:

You are an experienced software engineer. The user will present a project idea but may not know the best tech stack to use. The user might not even know if it should be a website, a standalone app, or just a Python script. Your job is to help the user understand what tech stack to use and to explain your choices.

You can locate these agent markdown files in the .claude/agents/ directory, either within your project or user directory structure. Under agents, you will find a list of all the agents you have created as markdown files.

Here is a look at my tech-stack-advisor.md:

It contains the name, a description, and several examples.

Context:

User wants to build something but isn't sure what technology to use.

User: I want to create something that helps people track their daily habits, but I'm not sure if I should make a website or an app or what.

Assistant: Let me use the text advisor agent to help you determine the best technology approach for your habit tracking project.

Claude generated all of this, including numerous other examples. Then, it provides a detailed definition:

You are a senior software architect and technology consultant with over 15 years of experience. Your primary mission is to help users identify the optimal technology stack.

The definition continues with its approach, questions to ask, the analysis to perform, required QA, and the final goal. This is remarkably thorough. All I provided was a simple prompt, and Claude Code handled the rest, building out this comprehensive agent.

Putting the Advisor to the Test

Now that I had a tech stack advisor, I needed it to advise me. I prompted Claude: "I'd like to use the techstack adviser to help me create a new project. I want the project to create a little sketch pad that has flowers trailing behind when you draw in it."

The tech stack advisor sub-agent processed this for a few moments and returned with its recommendations, outlining the platform, core technologies, and architecture it would use. It then asked if I wanted help creating a basic prototype. Naturally, I agreed.

The result is a functional flower sketch pad where I can even change the brush size. A great success for the sub-agent.

Building a UI Project Auditor Agent

Next, let's create another agent.

/agent create new

I'll scope it to the project level and generate it with Claude. My prompt is:

I would like a UI engineer agent to take a look at the project that we have so far and make recommendations for best coding practices and sort of usage of the project and recommend any enhancements it thinks might be a good idea.

This is where you select the tool usage. You can grant access to everything or restrict it to read-only. For this case, I need the agent to be an expert, so I'll provide full access. If you have a highly specialized agent, you can configure permissions tool by tool.

You also get to assign a color to the agent, so you can visually identify when it's active. After reviewing the generated configuration, you can confirm and save.

Now, I have a new agent: ui-project-auditor.md. Let's examine the file created in the .claude/ directory. The file provides a description, examples, context, and an overall mission for this custom agent. It details what to focus on, what to analyze, and guidelines for its recommendations, such as: "Always provide specific actionable advice with reasoning."

Auditing the Project

Let's put this new agent to work. I'll ask it to: "use the UI project auditor and take a look at this project and see what recommendations for improvement."

The agent, highlighted in its designated color, gets to work. It returns with a list of recommendations, having identified several critical issues: - Security risks - Potential memory leaks - Significant accessibility gaps

It provided a list of top recommendations and suggestions. I then instructed it to apply the changes based on its own recommendations.

After it finished, I tested the application. The agent mentioned it would throttle flower creation to manage memory. The effect was noticeable, so I asked it to update the flower generation to be more prolific, which it did successfully.

Final Thoughts

That is a brief overview of Claude Code's sub-agents. They are a simple and elegant solution to many complex problems. I will certainly be using them extensively in the future to enhance my code in ways I might not have considered. This feature gives an already powerful tool even more superpowers. Have fun building your own agent army.