Getting Started with Claude Code Agents
If you've been using Claude Code for a while, you've probably noticed that long sessions get messy. You ask Claude to search through a bunch of files, it reads dozens of them, and now your context window is half full of file contents you don't need anymore. Or you want Claude to do the same kind of review on every project, but you have to re-explain the rules every time.
Agents (officially called subagents in the Claude Code docs) solve both of those problems.
What are subagents?
A subagent is a specialized AI assistant that runs inside Claude Code with its own system prompt, its own set of tools, and its own context window. The subagent does its work and returns just the result. Your main conversation stays clean. Claude delegates to a subagent automatically only when the agent's description contains an explicit trigger, like "Use after making code changes". Without that, you invoke agents yourself.
Claude Code ships with a few built-in subagents you're probably already using without knowing it. Explore runs on Haiku (faster, cheaper) with read-only tools and handles codebase search. Plan is similar but used in plan mode to gather context before presenting a plan. General-purpose has access to all tools and handles complex multi-step tasks. These run automatically. You don't invoke them directly.
Why create custom subagents?
Custom subagents are useful when you keep doing the same kind of task and want consistent behavior across sessions, or when you want to isolate a task and keep your main conversation focused.
Think of a code reviewer that checks for security issues after every feature, a documentation writer that knows how you like your docs formatted, or a test generator that follows your project's specific testing patterns. You can also create agents with access to a specific MCP server that the main conversation doesn't need.
Creating your first subagent
The easiest way is with the /agents command. Type it in Claude Code and it opens a tabbed interface. Go to the Library tab, hit Create new agent, and choose where to save it.
There are two scopes. Personal saves to ~/.claude/agents/ and makes the agent available in all your projects. Project saves to .claude/agents/ in your current project, which you can check into version control. For something like a code reviewer you want everywhere, choose Personal. For something specific to one codebase, choose Project.
Claude Code can generate the agent for you. Pick Generate with Claude, describe what you want, and it writes the system prompt. You can also restrict which tools the agent has access to and pick a model (Haiku for fast/cheap tasks, Sonnet for balanced, Opus for complex reasoning).
What subagent files look like
Subagents are Markdown files. Here's a minimal example:
---
name: code-reviewer
description: Reviews code for quality and best practices. Use after making code changes.
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the changed files and provide
specific, actionable feedback on quality, security, and best practices.
Focus on: potential bugs, security issues, code clarity, and test coverage.
Only name and description are required. Everything else is optional. The description is what Claude uses to decide when to delegate. Write it clearly. After editing an agent file manually, restart Claude Code to load it.
Using agents in a conversation
You can invoke agents explicitly:
Use the code-reviewer agent to check the changes in src/auth/
Or you can set things up so Claude figures it out. If your agent's description says "Use after making code changes", Claude will often delegate automatically after it writes code.
A great starting point: agency-agents
Writing agent system prompts from scratch takes practice. Knowing what to include, how to phrase the instructions, and what constraints to set isn't obvious when you're new to this.
agency-agents is a collection of 144+ ready-made agents across 12 domains: engineering, design, marketing, testing, game development, and more. Each agent has a distinct personality, domain-specific workflows, and concrete deliverables baked into the prompt.
To install all engineering agents for Claude Code:
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh --tool claude-code
Or copy specific agents manually:
cp engineering/*.md ~/.claude/agents/
The files drop straight into ~/.claude/agents/ with no conversion needed. After restarting Claude Code, you'll have agents like Frontend Developer, Backend Architect, Security Engineer, and more available.
Even if you don't use them as-is, they're worth reading. Looking at how a well-crafted agent prompt is structured teaches you a lot about what makes an agent actually useful.
Keeping context under control
One of the main reasons to use subagents is context management. When you run a search-heavy task through an agent, all those file reads happen in the agent's context window, not yours. You get back a summary, and your conversation stays usable.
This matters more as sessions get longer. If you're working on a big feature and Claude has to explore a large codebase, routing that exploration through an agent keeps your main context free for the actual work.
More agent options
A few more fields worth knowing once you're past the basics:
---
name: security-auditor
description: Audits code for security vulnerabilities. Use proactively after auth changes.
tools: Read, Glob, Grep
model: opus
disallowedTools: Write, Edit
permissionMode: plan
memory: user
color: red
---
disallowedTools lets you block specific tools even if tools would otherwise allow them. permissionMode: plan means the agent will show you a plan before doing anything. memory: user gives the agent persistent memory across all your projects. Use project instead if the knowledge should be specific to one codebase.
Where to go from here
The official subagents documentation covers everything including agent teams, background agents, and hooks. Start simple: make one agent for the most repetitive thing you ask Claude to do, and go from there.