Skip to content
Home › Claude Code Configuration & Workflows

Filesystem Subagents (.claude Agents)

Claude Code Configuration & Workflows

Definition

Subagents defined as Markdown files with YAML frontmatter under .claude/agents/*.md, one of three ways to create subagents (alongside the programmatic agents param and the built-in general-purpose).

Key points

  • Required frontmatter: name (lowercase + hyphens; hooks receive it as agent_type), description. Optional: tools, disallowedTools, model (defaults to inherit), permissionMode (default/acceptEdits/auto/dontAsk/bypassPermissions/plan/manual), maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation (worktree = temp git worktree), color, initialPrompt.
  • File precedence (high→low): Managed settings > --agents CLI flag > .claude/agents/ (project) > ~/.claude/agents/ (user) > plugin agents/. Plugin subagents don't support hooks/mcpServers/permissionMode.
  • Programmatic AgentDefinition defs take precedence over filesystem defs of the same name.
  • Built-in subagents: Explore (read-only), Plan (read-only, plan mode) — see Plan Mode And Explore Subagent — and general-purpose.
  • Model resolution: CLAUDE_CODE_SUBAGENT_MODEL env → per-invocation model → frontmatter model → main model.
  • Subagents inherit their own system prompt + the Agent tool prompt, project CLAUDE.md (via settingSources), and tool definitions; they do not receive parent conversation history, tool results, or system prompt.

Why it matters for the exam

  • D3 (20% of scored content) tests the frontmatter fields (esp. model defaulting to inherit), the file-precedence chain, and that subagents are invoked via the Agent tool.

Common gotchas

  • Filesystem model defaults to inherit, whereas a programmatic AgentDefinition omitting tools inherits all tools — different defaults for different creation paths.
  • Task→Agent rename: subagents are invoked via the Agent tool, but "Task" still appears in system:init tools and in permission_denials[].tool_name — check both (see Task and Agent tool).
  • Programmatic defs override same-named filesystem defs.

See also

Sources

Referenced by