More Control Over Subagents

You get a lot of control over a custom subagent from its frontmatter. You can pick its model and effort, limit its tools, cap its turns, give it its own worktree or memory, and you can now also skip your CLAUDE.md files with omitClaudeMd: true.

A narrow worker

---
name: log-scanner
description: Scans CI logs for the first failing step and reports it
model: sonnet
effort: low
memory: project
omitClaudeMd: true
---

Find the first failing step in the log you are given and report the
command, the error and the file it points to.

Save it as .claude/agents/log-scanner.md. Only name and description are required. Everything else is optional.

Every subagent normally loads your CLAUDE.md files into its fresh context first, but a narrow worker like this log scanner doesn’t need your repo conventions. Leaving them out keeps its context small and each spawn quick to start.

What omitClaudeMd skips

• It skips the user, project, and local CLAUDE.md files.
• Managed policy files still load.
• It is ignored when the agent runs as the main session agent through --agent or the agent setting.
• It requires Claude Code v2.1.271 or later.

Use it for subagents that take everything they need from the delegation prompt. Do not use it for a reviewer or implementer that is supposed to follow your conventions, because those conventions live in the files you just turned off.

The fields worth knowing

Field	What it does
model	sonnet, opus, haiku, fable, a full model ID, or inherit.
effort	low, medium, high, xhigh, or max. Overrides the session effort level.
tools	Allowlist of tools. If you omit it, the subagent inherits every tool available to subagents.
disallowedTools	Tools to remove from the inherited or listed set.
maxTurns	Stops the subagent after this many agentic turns.
isolation	Set to worktree to run it in a temporary git worktree.
memory	user, project, or local. Lets the subagent keep notes across sessions.
skills	Skills to preload. The full skill content is injected at startup, not only the description.
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, or plan.
background	Set to true to keep it in the background even when Claude asks for the foreground.
color	Display color in the task list and transcript.

Details that are easy to miss

• A disallowedTools entry with a specifier, such as Bash(git push *), still removes the whole tool. You cannot use it to block one command pattern and keep the rest of Bash.
• If no entry in tools resolves to a real tool, the subagent usually fails to launch with an error naming the entries.
• When a subagent reaches maxTurns, its output comes back marked as partial, and Claude can resume it to continue (v2.1.246 or later).
• A worktree from isolation: worktree branches from your default branch by default, not from the parent session’s HEAD. Uncommitted or unmerged work in your session is not in it. The worktree is cleaned up automatically if the subagent makes no changes.
• Names cannot contain :, which is reserved for plugin subagents such as my-plugin:reviewer. Claude Code skips a file whose name contains one and only logs the error to the debug log.
• permissionMode, mcpServers, and hooks are ignored for plugin subagents.

Rule of thumb

Match the frontmatter to the job. A log scanner or file finder can run on a small model at low effort with no CLAUDE.md. A reviewer needs your conventions, a stronger model, and read-only tools. See What a subagent actually knows for what reaches a subagent in the first place.