Subagent Frontmatter - Claude Code

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