Custom Agents

One of the features that changed how I use Claude Code is custom agents (subagents). Instead of giving Claude Code the same instructions over and over, you define a specialized agent once and it gets used automatically when the task matches.

Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent’s description, it delegates to that subagent, which works independently and returns results.

1. Why use custom agents?

Before I started using agents, I would repeat the same kind of instructions across sessions: “review this code for security issues”, “commit with signed commits and no co-author lines”, “debug this systematically”. Custom agents solve this by encoding those workflows once.

They help you:

• Preserve context by keeping specialized work out of your main conversation
• Enforce constraints by limiting which tools a subagent can use
• Specialize behavior with focused system prompts for specific domains
• Control costs by routing simple tasks to faster models like Haiku

2. How they work

a. File structure

Agents are Markdown files with YAML frontmatter. The frontmatter defines metadata and the body becomes the system prompt.

---
name: my-agent
description: When Claude should use this agent
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

You are a specialist in [domain]. When invoked, do [specific workflow].

b. Where to store them

c. Key frontmatter fields

3. My agents

Here are the agents I actually use daily. I built each one to solve a specific friction I kept running into.

a. Pusher (git operations)

This one was born from frustration. I wanted signed commits, no co-author footers, and clean commit messages every time. Instead of remembering all that, this agent handles it.

---
name: pusher
description: Git operations agent specializing in safe commit and push workflows. Always uses signed commits (-S), excludes co-author lines, and removes all footers.
tools: Bash, Read, Grep, Glob
model: sonnet
color: purple
---

What it does:

1. Checks git status and git diff to understand changes
2. Generates a commit message based on actual diffs
3. Scans for co-author lines and footers, blocks if found
4. Executes git commit -S with the generated message
5. Pushes to remote

I use model: sonnet here because commit message generation doesn’t need Opus-level reasoning.

b. Debugger

When something breaks, I don’t want Claude Code to just try random fixes. This agent forces a systematic investigation: gather symptoms, form hypotheses, test them, then fix.

---
name: debugger
description: Expert debugging agent with systematic root cause analysis methodology. Specializes in complex system debugging, performance analysis, and security vulnerability investigation.
tools: Read, Edit, Bash, Grep, Glob
color: blue
---

The system prompt defines a 5-step methodology:

1. Symptom Analysis: What exactly is failing, when, under what conditions?
2. Multi-Layer Investigation: Application, integration, infrastructure, environment
3. Hypothesis-Driven Analysis: Form theories, define evidence requirements
4. Systematic Investigation: Collect data, reconstruct timeline, isolate components
5. Solution Validation: Confirm root cause, regression test, prevention strategy

The agent doesn’t jump to fixing. It investigates first.

c. Security auditor

This is a read-only agent. It can’t write or edit files, which is intentional. A security review should observe and report, not modify code.

---
name: security-auditor
description: Review code for vulnerabilities, implement secure authentication, and ensure OWASP compliance. Use PROACTIVELY for security reviews, auth flows, or vulnerability fixes.
tools: Read, Grep, Glob
---

Notice the tools field only includes read-only tools. The description says “use PROACTIVELY”, which tells Claude to delegate security-related tasks to this agent automatically.

Focus areas:

• Authentication/authorization (JWT, OAuth2, SAML)
• OWASP Top 10 vulnerability detection
• Secure API design and CORS configuration
• Input validation and SQL injection prevention
• Encryption implementation

d. Suggestor (feature analysis)

When I’m considering adding a feature, I don’t want a quick opinion. I want research: codebase analysis, industry best practices, pros/cons, implementation effort.

---
name: suggestor
description: Expert feature analysis and recommendation agent. Specializes in evaluating potential features, analyzing codebases, and providing detailed pros/cons analysis.
tools: Bash, Glob, Grep, Read, Edit, Write, WebSearch, WebFetch, TodoWrite
color: orange
---

This agent has broad tool access including WebSearch and WebFetch because it needs to research industry patterns and competitor approaches. It provides structured recommendations:

• RECOMMEND: Strong rationale to implement
• CONSIDER: Mixed benefits, needs careful evaluation
• AVOID: Clear reasoning against
• ALTERNATIVE: Better approaches to the same goal
• FUTURE: Consider for later phases

e. UI/UX designer

Design decisions benefit from structured thinking. This agent applies a multi-perspective analysis framework before suggesting any UI changes.

---
name: uiux
description: Expert UI/UX designer agent with deep design psychology knowledge. Automatically applies structured analysis for complex design challenges, accessibility, and design system architecture.
tools: Bash, Glob, Grep, Read, Edit, Write, WebSearch, TodoWrite
color: green
---

The system prompt includes:

• Problem Decomposition: User, business, and technical dimensions
• Multi-Perspective Analysis: Primary users, edge cases, accessibility, stakeholders
• Constraint Identification: Technical, business, and human factors
• Solution Generation: Multiple approaches with trade-off analysis
• Validation Strategy: Testing methods and success metrics

4. Creating your own

a. Using the interactive command

The fastest way to create an agent:

claude
> /agents

Select Create new agent, choose scope (user or project), and either write it yourself or let Claude generate it.

b. Manual creation

Create a .md file in ~/.claude/agents/ (user-level) or .claude/agents/ (project-level):

# User-level
mkdir -p ~/.claude/agents
# Then create your .md file there

# Project-level
mkdir -p .claude/agents
# Then create your .md file there

c. Tips for good agents

• Write clear descriptions: Claude uses this to decide when to delegate. Include trigger phrases like “use proactively” or “use when debugging”
• Limit tool access: A security auditor shouldn’t have write access. A researcher doesn’t need edit
• Use cheaper models for simple tasks: model: sonnet or model: haiku for tasks that don’t need deep reasoning
• Define a clear workflow: Numbered steps in the system prompt keep the agent focused
• Keep prompts focused: One agent, one job. Don’t make a “do everything” agent

5. Built-in agents

Claude Code comes with several built-in agents you don’t need to configure:

The Explore agent is particularly useful. It runs on Haiku (fast and cheap) and keeps verbose search results out of your main context.

6. Foreground vs background

Agents can run in the foreground (blocking) or background (concurrent):

• Foreground: Blocks your conversation until done. Permission prompts pass through to you
• Background: Runs while you keep working. Pre-approves permissions before starting

You can ask Claude to “run this in the background” or press Ctrl+B to background a running agent.

Background agents are great for parallel research where multiple independent investigations can run simultaneously.