Creating Custom Agents
Define your own agents
What sub-agents in Claude Code are
A sub-agent is a specialized helper that you define once and then call for a narrow, repeatable task. Unlike the main conversation, a sub-agent runs in its own context window: it receives only its instruction and returns only its result, without flooding the main session with intermediate steps. This has two practical effects. First, the main conversation stays short and focused, because heavy code search or dependency analysis happens off to the side. Second, each role can use its own model and its own set of tools, instead of granting one agent full access to everything.
Technically, a sub-agent is just a Markdown file with YAML frontmatter at the top. That is exactly what the code block above describes: the model field selects the model (haiku, sonnet, or opus), and the tools field lists the allowed tools — for example Read, Grep, and Glob. Everything after the closing --- is the agent's system prompt: its role, focus areas, and required output format. When the example above lists only read and search tools, the agent physically cannot modify a single file — that is the point of tool restriction: an "auditor" is read-only by definition.
When to use them and common mistakes
Sub-agents shine when a task is clear, repeatable, and context-heavy: security review, test generation, dependency auditing, documentation drafting. The scope determines where the agent file lives: .claude/agents/ in the project makes the agent shared with the team, while ~/.claude/agents/ in your home directory keeps it personal and available across all projects. A concrete example: create a security-auditor.md file with the haiku model and only the Read/Grep/Glob tools, describe in the body what to look for (SQL injection, XSS, authentication issues) and how to format results — then you can invoke that agent again and again without rewriting the instruction. The most common beginner mistake is giving a sub-agent broad permissions and a vague role: it then behaves like a generic chat, loses predictability, and may change more than intended. Keep the role narrow, the tool list minimal, and the output format explicit.
An agent is defined in a Markdown file with YAML frontmatter:
--- model: haiku tools: - Read - Grep - Glob --- # Security Auditor You are a security-focused code reviewer. Your job is to find potential security vulnerabilities in the codebase. ## Focus Areas - SQL injection - XSS vulnerabilities - Authentication issues - Sensitive data exposure - Input validation ## Output Format For each issue found, provide: 1. File and line number 2. Vulnerability type 3. Risk level (High/Medium/Low) 4. Suggested fix
Frontmatter structure:
model— model (haiku/sonnet/opus)tools— list of available tools
Document body:
- • Instructions for the agent
- • Task description
- • Output format
| Model | Speed | Cost | Use Case |
|---|---|---|---|
haiku | Very fast | Low | Simple tasks |
sonnet | Fast | Medium | Most tasks |
opus | Slow | High | Complex tasks |
💡 Use haiku for quick search tasks, sonnet for most tasks, opus for complex analysis
Specify only the tools the agent needs:
File
Execution
Web
Interactive
⚠️ Agent without Edit and Write cannot modify files — useful for read-only auditors
In current session memoryAgent exists only during the session.claude/agents/Available to everyone in this project~/.claude/agents/Available in all your projectsGenerates code documentation
Creates unit tests
Checks dependencies for vulnerabilities
Plans database migrations
Best Practices for Creating Agents
- 1.Give the agent a clear role and limited set of tools
- 2.Use haiku for quick tasks, sonnet for complex ones
- 3.Describe output format for predictable results
- 4.Store common agents in ~/.claude/agents/ for reuse
Frequently asked questions
What are sub-agents in Claude Code?
A sub-agent is a specialized helper defined in a Markdown file with YAML frontmatter. It runs in its own context window, receives only its instruction, and returns only its result without flooding the main session. Each role can use its own model and a limited set of tools.
How do I create a custom agent in Claude Code?
Create a Markdown file such as security-auditor.md in .claude/agents/ (project scope) or ~/.claude/agents/ (user scope). In the YAML frontmatter set the model field (haiku/sonnet/opus) and a tools list. Below the closing ---, describe the agent's role, focus areas, and output format — that is its system prompt.
What is the difference between haiku, sonnet, and opus for agents?
haiku is the fastest and cheapest, good for simple search tasks. sonnet is fast and medium cost, suited for most tasks. opus is slow and expensive but best for complex analysis such as planning database migrations. Match the model to the agent's task complexity.
How do I restrict an agent's tools in Claude Code?
List only the needed tools in the tools field, for example Read, Grep, Glob. Omitting Edit and Write means the agent physically cannot modify files — ideal for read-only auditors. A minimal tool set keeps the agent predictable and safe.
This lesson is part of a structured LLM course.
My Learning Path