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 decisionssonnet - General development, balanced speed/qualityhaiku - 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:
- File is at the correct location
- YAML frontmatter parses correctly (no syntax errors)
- 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
1---2name: subagent-creator3description: Create new Claude Code custom agents (subagents). Use when: (1) User wants to create a new custom agent, (2) User says 'create agent', 'new agent', 'make subagent', (3) User wants a specialized agent for delegation. Covers agent file format, YAML frontmatter, tool restrictions, model selection, permission modes, persistent memory, placement.4---56# Create Custom Agent78## Agent File Format910Custom agents are **Markdown files with YAML frontmatter** stored in:1112| Location | Scope |13|----------|-------|14| `$HOME/.claude/agents/` | All projects (personal) |15| `.claude/agents/` | Current project only |1617## Frontmatter Fields1819| Field | Required | Description |20|-------|----------|-------------|21| `name` | Yes | Lowercase letters and hyphens identifier |22| `description` | Yes | What the agent does. Claude uses this to decide when to delegate |23| `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) |24| `tools` | No | Allowlist of tools. Inherits all if omitted. Use `Task(agent-name)` to restrict subagent spawning |25| `disallowedTools` | No | Denylist of tools |26| `permissionMode` | No | `default`, `acceptEdits`, `delegate`, `dontAsk`, `bypassPermissions`, `plan` |27| `maxTurns` | No | Max agentic turns before stopping |28| `skills` | No | Skills to preload at startup |29| `mcpServers` | No | MCP servers available to agent |30| `hooks` | No | Lifecycle hooks scoped to agent |31| `memory` | No | `user`, `project`, or `local` - persistent memory across sessions |32| `color` | No | Color for UI display |3334## Workflow3536### Step 1: Understand the agent's purpose3738Ask user:3940- What tasks should this agent handle?41- Should it be personal (`$HOME/.claude/agents/`) or project-scoped (`.claude/agents/`)?42- Does it need write access or is it read-only?4344### Step 2: Choose appropriate settings4546**Model selection:**4748`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.4950- `opus` - Complex reasoning, code review, architecture decisions51- `sonnet` - General development, balanced speed/quality52- `haiku` - Fast simple tasks, formatting, quick lookups5354**Tool restrictions:**5556- Read-only agent: `tools: Read, Grep, Glob`57- Developer agent: omit `tools` (inherits all)58- No web access: `disallowedTools: WebFetch, WebSearch`5960**Key constraints:**6162- Subagents CANNOT spawn other subagents (no nesting)63- Keep the body focused - it becomes the agent's system prompt6465**Path safety -- NEVER use `~` in agent instructions:**6667- 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 directory68- In agent instructions, ALWAYS write `$HOME` instead of `~` for home directory paths. For example: `$HOME/cclogs/...` not `~/cclogs/...`, `$HOME/.claude/...` not `~/.claude/...`69- This applies to all file paths in the agent body: log directories, config paths, output directories, temp file locations, etc.7071### Step 3: Create the agent file7273Template:7475```markdown76---77name: agent-name78description: One sentence describing when Claude should delegate to this agent79model: sonnet80tools: Read, Grep, Glob, Bash81---8283You are a specialized [role]. [Core instruction in 1-2 sentences.]8485## Responsibilities8687[What this agent does - keep concise]8889## Workflow9091[Step-by-step procedure if applicable]92```9394### Step 4: Format the agent file9596Format the created agent file using the mdx-formatter to ensure consistent markdown formatting:9798```bash99pnpm dlx @takazudo/mdx-formatter --write <path-to-agent-file.md>100```101102### Step 5: Verify103104After creating the file, verify:1051061. File is at the correct location1072. YAML frontmatter parses correctly (no syntax errors)1083. Description clearly indicates when to use the agent109110## Examples111112### Read-only code explorer113114```yaml115---116name: code-explorer117description: Explore and explain codebase architecture and patterns118tools: Read, Grep, Glob119model: sonnet120---121122You are a codebase explorer. Analyze code structure,123explain architecture, and find patterns.124```125126### Developer with memory127128```yaml129---130name: project-dev131description: Project-aware developer that learns conventions over time132model: opus133memory: project134---135136You are a developer for this project. Maintain memory of137conventions, patterns, and architectural decisions.138```139140## Reference141142- Agents are used via Task tool's `subagent_type` parameter143- Skills can use agents via `context: fork` + `agent: agent-name`144- Run directly: `claude --agent agent-name`
takazudo