🎭

Custom Agents

Specialized AI personas with specific expertise, tools, and instructions. Like hiring specialists for your team: a code reviewer, a copywriter, a stock analyst.

Concept·6 sections·1 min read

01What Are Custom Agents

The hiring analogy

When you create an agent, you define three things: what it knows (system prompt), what it can do (tools), and when it should activate (description). The result is a focused, repeatable AI collaborator that excels at a narrow task instead of being mediocre at everything.

Base Claude

Knowledge

General training data

Tools

All available tools

Behavior

Helpful, broad

Consistency

Varies with prompt

Analogy

A general practitioner

Custom Agent

Knowledge

Focused system prompt with domain expertise

Tools

Only the tools you grant

Behavior

Opinionated, specialized

Consistency

Same approach every time

Analogy

A cardiologist for your heart

02How They Work

An agent is a Markdown file with YAML frontmatter at the top and a system prompt in the body. Each field controls a different aspect of the agent's behavior.

# Agent file structure
---
name: agent-name
description: "When to use this agent"
model: opus
color: green
tools: Read, Grep, Glob
---

System prompt goes here. This defines the
agent's behavior, personality, and expertise.

🏷️

name

Kebab case identifier (lowercase, words separated by hyphens). This is how you reference the agent.

📝

description

Tells Claude when to activate this agent. Include example user messages so Claude can select the right agent automatically.

🧠

model

Which Claude model to use. Opus for complex reasoning, sonnet for balanced tasks, haiku for fast simple tasks.

🎨

color

Display color in the terminal. Options: green, blue, cyan, red, yellow, magenta.

🔧

tools

Comma separated permissions. Read, Grep, Glob for read only. Add Write, Edit, Bash for agents that make changes.

📄

body

The system prompt that defines behavior. Put the agent's expertise, rules, output format, and personality here.

Critical rule

The frontmatter --- MUST start on line 1 of the file. If there is a blank line before it, the agent silently fails to load. No error message; it just will not appear.

03Where They Live

Global Agents

Location

<code>~/.claude/agents/</code>

Availability

Available in every project on your machine

Best for

Personal productivity agents: code reviewer, writing assistant

Project Agents

Location

<code>.claude/agents/</code> in your project root

Availability

Available only in that project

Best for

Project specific roles. Can be committed to git and shared with your team.

04Types You Can Build

💻

Coding and Engineering

Code reviewer, senior architect, design system critic. Agents that analyze code quality, enforce patterns, and catch issues.

✍️

Marketing and Writing

Copywriter, email strategist, content editor. Each with different voice, format, and audience awareness.

📊

Finance and Analysis

Stock analyst, crypto analyst, financial modeler. Agents with specific frameworks and output formats for investment research.

⚙️

Operations and Workflow

Claude Code advisor, project manager, documentation writer. Agents that improve how you work with Claude itself.

05Agents vs Skills vs Subagents

	Agent	Skill	Subagent
What it is	A persona with expertise	A knowledge document	A delegated task runner
Analogy	Hiring a specialist	Giving someone a manual	Assigning someone a task
Defined by	.md file with frontmatter	SKILL.md in a subfolder	Task tool invocation in code
Persistence	Lasts the whole session	Loaded on demand	Runs and returns results
Context cost	Full system prompt always loaded	~100 tokens until triggered	Separate context window
Best for	Consistent persona and behavior	Repeatable processes	Parallel or isolated work

They compose beautifully

A code reviewer agent (the persona) can invoke a review checklist skill (the process) and spawn subagents to review different files in parallel (the delegation).

06Example: Code Reviewer

# ~/.claude/agents/code-reviewer.md
---
name: code-reviewer
description: "Reviews code for quality, security, and best practices."
model: opus
color: cyan
tools: Read, Grep, Glob
---

You are a senior code reviewer with 15 years of experience.

## Review Process
1. Read all changed files
2. Check for bugs, security vulnerabilities, performance issues
3. Evaluate code style and consistency
4. Suggest concrete improvements with code examples

## Output Format
For each issue: File/line, Severity, Issue, Fix

## Rules
Be specific. Praise good patterns. Focus on substance.
Flag security issues as critical, always.

🔒Read only tools because a reviewer should analyze, not modify

📋Clear process ensures consistent, thorough reviews

📐Defined output format makes every review actionable

📏Specific rules keep reviews focused on substance, not style