Claude Code - Subagent Frontmatter

claude-code-subagent-frontmatter.md

Claude Code - Subagent Frontmatter

Note: This information applies at the time of writing and may be subject to change in future versions of Claude Code.

Overview

When creating subagents in Claude Code, the frontmatter configuration defines how the orchestrator identifies and delegates tasks to your agent. The frontmatter is straightforward and requires only three mandatory fields.

Mandatory Fields

1. name

The agent's identifier/name.

Example: evaluator, code-generator, documentation-writer

2. description

This is the key field. The description defines the logic by which the orchestrator picks a subagent for delegation. It should clearly explain when and why this agent should be invoked.

Example: "Invoke this agent to run the evaluations for ideas proposed by the user"

3. model

Specifies which model the agent should use. Can be set to inherit to use the parent orchestrator's model, or explicitly specify a model like sonnet, opus, or haiku.

Example: inherit, sonnet, haiku

Basic Example

Here's a minimal frontmatter configuration:

---
name: evaluator
description: Invoke this agent to run the evaluations for ideas proposed by the user
model: inherit
---

Key Takeaways

• Only 3 fields required: name, description, and model
• Description is critical: It determines when the orchestrator delegates to this agent
• Model flexibility: Use inherit to adopt the orchestrator's model or specify explicitly
• Keep it simple: The frontmatter is intentionally minimal to reduce complexity

Best Practices

• Write clear, specific descriptions that explain the agent's purpose and when it should be invoked
• Use inherit for model unless you have a specific reason to use a different model (e.g., using haiku for quick, straightforward tasks to minimize cost)
• Choose descriptive agent names that reflect their function

---

About this Gist

This gist was generated using Claude Code to document subagent frontmatter configuration. While the information is accurate at the time of writing, please verify against the official Claude Code documentation for the most up-to-date specifications.

Users should validate this information and refer to the official Claude Code documentation for authoritative guidance.