Sub-Agents: Specialist Assistants in Claude Code

As your projects grow, one general assistant trying to do everything starts to create problems.

Claude is asked to write copy for a homepage. While doing that, it accidentally changes the CSS layout. Or you ask it to review the structure of your site and it starts editing content it was not supposed to touch.

This happens because Claude is doing everything at once: writing, designing, reviewing, and building, all in one session with no clear separation of roles.

Sub-agents are how you fix this.

What a sub-agent is

A sub-agent is a specialist version of Claude with a specific role, specific knowledge, and specific limits.

Instead of one general Claude doing everything, you define a team. Each team member has one job and clear boundaries on what they can and cannot touch.

A design agent whose only job is styling reads your CSS and suggests changes but never touches your HTML content. A content agent whose only job is writing and editing text never touches code. A review agent whose only job is checking what has been built and flagging problems never makes changes itself.

Each agent has its own context window, which means it is not confused by everything that happened in the rest of your session. It starts focused and stays focused.

Where sub-agents live

Claude Code stores sub-agents as Markdown files in a specific folder. You have two options.

Personal sub-agents are available across all your projects and live here:

On Mac: /Users/yourname/.claude/agents/

On Windows: C:\Users\yourname.claude\agents\

Project sub-agents are available only in one specific project and are stored in a folder called .claude/agents/ inside your project root. These are also shared with a team if you use GitHub.

If you have both, project-level agents take priority over personal ones when they share the same name.

How to create a sub-agent

The easiest way is using the /agents command.

Open Claude Code in any session. Type /agents and press Enter. Claude shows you a list of your existing sub-agents if you have any. Select "Create new agent." Choose whether this is a personal agent or a project agent. Select "Generate with Claude" and describe the agent in plain language.

Prompt:

A CSS specialist who only edits style.css and style-related files. It never touches HTML content or images. Its job is to improve visual design, fix layout issues, and keep the styling consistent.

Claude writes the full agent definition for you based on your description.

What a sub-agent definition looks like

If you want to create one manually, here is the format. The file is saved inside the .claude/agents/ folder with a name that matches the agent, for example design-agent.md.

The file starts with a header block at the top containing three pieces of information: the name of the agent, a description of what it does, and the tools it is allowed to use. Below that you write the agent's instructions in plain language.

A design agent file would look like this:

Header block:

• name: design-agent
• description: Handles all CSS and visual styling. Never touches HTML content or images.
• tools: Read, Edit

Instructions:

You are a specialist CSS and design agent.

Your responsibilities:

• Edit style.css and any CSS files only.
• Fix layout, spacing, colour, and typography issues.
• Keep the visual design consistent with established styles.

Your limits:

• Never modify HTML files or content.
• Never touch the /images/ folder.
• Never add JavaScript.
• If a task requires HTML changes, tell the user rather than doing it yourself.

How to use a sub-agent

Once a sub-agent is created, you can call it in a session by name.

Prompt:

Use the design-agent to fix the spacing on the homepage.

Claude will delegate that task to the specialist agent, which starts with its own focused context and stays within its defined boundaries. In some cases Claude may suggest using a matching agent automatically if it recognises the task fits an agent's role, though you can always call the agent directly by name to be certain.

When do you actually need sub-agents?

For your first few projects, you do not need them.

A single Claude session with a well-written CLAUDE.md is enough for most things including websites, landing pages, and portfolios. Sub-agents become valuable when you are building something large with clearly separate areas such as design, content, backend, and review. They also help when you keep running into Claude making changes across areas you did not want touched, or when you want consistent specialist behaviour across multiple projects.

Most students in this community will start needing sub-agents when they are building multi-page web apps, automations, or AI tools. At that point the structure becomes genuinely helpful.

For now: know that sub-agents exist, understand what they do, and come back to this lesson when your projects are large enough to need them.

What about AGENTS.md?

You may have heard of a file called AGENTS.md used by other AI coding tools such as GitHub Copilot and OpenAI Codex. These tools use AGENTS.md the same way Claude Code uses CLAUDE.md: as a memory and context file.

AGENTS.md is not read by Claude Code. Claude Code reads CLAUDE.md.

If you ever work in an environment where multiple AI tools need the same context, you can reference an AGENTS.md file from within your CLAUDE.md using an @ reference like this:

Context

See also: @AGENTS.md

This tells Claude to also read that file during the session. For most people using only Claude Code, this is not something you will ever need.

Your action right now

If you want to try creating a sub-agent now, open Claude Code in your project and type /agents. Choose to create a new agent. Describe a simple specialist you would find useful, even something basic like a content editor who only touches text and never code. Let Claude generate it and review what it produces.

If this feels advanced right now, skip it and come back when you have a larger project that needs it. The skill will be here when you are ready for it.

Questions about sub-agents? Post in the community and tag Yar Malik.