Custom Subagents

You can create your own custom subagents in the ~/.claude/agents/ directory. An agent is simply a markdown file with frontmatter providing its configuration.

Basic example:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices.

Frontmatter fields:

name — the name used to explicitly trigger the subagent.
description — what will trigger the subagent.
tools — what tools it can use.
disallowedTools — what tools it can't use.
model — what Claude model to use.
permissionMode — what level of permission to ask.
maxTurns — how many turns it can run.
skills — skills it should be allowed to use.
mcpServers — MCP servers available to the subagent.
hooks — lifecycle hooks of the agent.
memory — persist memory at user, project, or local scope.
background — always run in background or not.
isolation — run in a temporary git worktree, away from your primary worktree.

Full example:

---
name: senior-code-reviewer
description: Delegate to this subagent when the user asks for a thorough code review, security audit, or wants feedback on a pull request. Also use when reviewing files for production readiness or architectural concerns.
tools: ["Read","Grep","Glob","Bash(git diff:*)","Bash(git log:*)"]
disallowedTools: ["Write","Edit","Bash(rm:*)","Bash(git push:*)"]
model: opus
permissionMode: dontAsk
maxTurns: 40
skills: ["code-quality-standards","security-checklist"]
mcpServers:
  - slack
  - github:
      type: stdio
      command: npx
      args:
        - -y
        - "@modelcontextprotocol/server-github"
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo '[reviewer] Running bash: $TOOL_INPUT' >> ~/.claude/logs/reviewer-audit.log"
  PostToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "echo '[reviewer] Read file: $TOOL_INPUT' >> ~/.claude/logs/reviewer-audit.log"
memory: project
background: false
isolation: worktree
---