Create Custom Agent

Agent File Format

Custom agents are Markdown files with YAML frontmatter stored in:

Location	Scope
$HOME/.claude/agents/	All projects (personal)
.claude/agents/	Current project only

Frontmatter Fields

Field	Required	Description
name	Yes	Lowercase letters and hyphens identifier
description	Yes	What the agent does. Claude uses this to decide when to delegate
model	No	sonnet, opus, haiku, fable, a full model ID (e.g. claude-opus-4-8), or inherit (default) — prefer inherit so the agent tracks the session model (currently Fable 5, a tier above Opus)
tools	No	Allowlist of tools. Inherits all if omitted. Use Task(agent-name) to restrict subagent spawning
disallowedTools	No	Denylist of tools
permissionMode	No	default, acceptEdits, delegate, dontAsk, bypassPermissions, plan
maxTurns	No	Max agentic turns before stopping
skills	No	Skills to preload at startup
mcpServers	No	MCP servers available to agent
hooks	No	Lifecycle hooks scoped to agent
memory	No	user, project, or local - persistent memory across sessions
color	No	Color for UI display

Workflow

Step 1: Understand the agent's purpose

Ask user:

• What tasks should this agent handle?
• Should it be personal ($HOME/.claude/agents/) or project-scoped (.claude/agents/)?
• Does it need write access or is it read-only?

Step 2: Choose appropriate settings

Model selection:

opus is not the top of the overall lineup (fable / the session model, currently Fable 5, sits above it) — when the agent should track whatever model is driving the session rather than being pinned, prefer inherit over hardcoding a model.

• opus - Complex reasoning, code review, architecture decisions
• sonnet - General development, balanced speed/quality
• haiku - Fast simple tasks, formatting, quick lookups

Tool restrictions:

• Read-only agent: tools: Read, Grep, Glob
• Developer agent: omit tools (inherits all)
• No web access: disallowedTools: WebFetch, WebSearch

Key constraints:

• Subagents CANNOT spawn other subagents (no nesting)
• Keep the body focused - it becomes the agent's system prompt

Path safety -- NEVER use ~ in agent instructions:

• WARNING: ~ (tilde) is only expanded by interactive shells. It is NOT expanded by Node.js fs operations, non-login shell contexts, or most programmatic file APIs. Using ~ in file paths passed to fs.writeFileSync, fs.mkdirSync, etc. will create a literal directory named ~ inside the working directory
• In agent instructions, ALWAYS write $HOME instead of ~ for home directory paths. For example: $HOME/cclogs/... not ~/cclogs/..., $HOME/.claude/... not ~/.claude/...
• This applies to all file paths in the agent body: log directories, config paths, output directories, temp file locations, etc.

Step 3: Create the agent file

Template:

---
name: agent-name
description: One sentence describing when Claude should delegate to this agent
model: sonnet
tools: Read, Grep, Glob, Bash
---

You are a specialized [role]. [Core instruction in 1-2 sentences.]

## Responsibilities

[What this agent does - keep concise]

## Workflow

[Step-by-step procedure if applicable]

Step 4: Format the agent file

Format the created agent file using the mdx-formatter to ensure consistent markdown formatting:

pnpm dlx @takazudo/mdx-formatter --write <path-to-agent-file.md>

Step 5: Verify

After creating the file, verify:

1. File is at the correct location
2. YAML frontmatter parses correctly (no syntax errors)
3. Description clearly indicates when to use the agent

Examples

Read-only code explorer

---
name: code-explorer
description: Explore and explain codebase architecture and patterns
tools: Read, Grep, Glob
model: sonnet
---

You are a codebase explorer. Analyze code structure,
explain architecture, and find patterns.

Developer with memory

---
name: project-dev
description: Project-aware developer that learns conventions over time
model: opus
memory: project
---

You are a developer for this project. Maintain memory of
conventions, patterns, and architectural decisions.

Reference

• Agents are used via Task tool's subagent_type parameter
• Skills can use agents via context: fork + agent: agent-name
• Run directly: claude --agent agent-name