Subagent Frontmatter - Claude Code
Configure model, tools, MCP, skills, memory, and scoping.
Subagent frontmatter is the YAML block that configures how a custom subagent behaves and what it can touch.
What it does
The frontmatter declares model, effort, allowed tools, MCP servers, skills, memory behavior, and scoping (project vs user). It's the contract between the subagent definition and the runtime. Claude honors every field when it spawns the agent, so getting the frontmatter right is how you build safe, predictable roles.
When to use it
- Every custom subagent definition needs frontmatter - this is your starting point.
- Tuning which MCP servers a subagent can reach.
- Pinning a subagent to a specific model for consistent output.
- Enabling persistent memory for long-lived roles.
Gotchas
- Tool allowlists are strict. A missing entry means the subagent fails the call, not that it asks.
- Model fields override session defaults when the subagent runs.
- Misspelled frontmatter fields silently fail. Run the agent once to confirm behavior.
Official docs: https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields
Technical content at the intersection of AI and development. Building with AI agents, Claude Code, and modern dev tools - then showing you exactly how it works.
Get the weekly deep dive
Tutorials on Claude Code, AI agents, and dev tools - delivered free every week.
Was this helpful?
