🏷️

Agent Frontmatter

The YAML frontmatter format that defines custom agents. Controls the agent name, description, model, tool access, and display color. Must start on line 1 of the .md file.

Configuration·2 sections·1 min read

codingworkflow

Install Prompt

Paste this into Claude Code to set it up:

Agent files live in ~/.claude/agents/ as .md files. The YAML frontmatter MUST start on line 1 (no blank line before the first ---). Fields: name (kebab-case), description (quoted string with examples), model (opus/sonnet/haiku), color (green/blue/cyan/red/yellow/magenta), tools (comma-separated tool names). The rest of the file is the agent's system prompt.

01What It Does

The agent's identity card

Every custom agent is a Markdown file with YAML frontmatter between --- delimiters at the top. The frontmatter defines who the agent is (name, description), what it can do (tools), how it thinks (model), and how it looks (color). The body below the frontmatter contains the system prompt that shapes the agent's personality and expertise.

Critical requirement: the first --- must be on line 1 of the file. If there is a blank line before it, the agent silently fails to load. There is no error message; it simply will not appear in your agent list.

02Field Reference

🏷️

nameA kebab case identifier (lowercase, words separated by hyphens). This is how you reference and invoke the agent. Examples: <code>code-reviewer</code>, <code>email-marketing</code>, <code>stock-analyst</code>. Keep it short and descriptive.

📝

descriptionTells Claude Code when to activate this agent automatically. Wrap it in double quotes, use <code>\n</code> for newlines, and include example user messages so Claude can match the right agent to the right request. The more specific your examples, the better the routing.

🧠

modelWhich Claude model powers this agent. Set <code>opus</code> for complex reasoning and architecture, <code>sonnet</code> for balanced everyday tasks, or <code>haiku</code> for fast, simple operations. The model choice directly affects the agent's capabilities and response speed.

🎨

colorThe display color in the terminal when this agent is active. Options: <code>green</code>, <code>blue</code>, <code>cyan</code>, <code>red</code>, <code>yellow</code>, <code>magenta</code>. Use color to visually distinguish between agents at a glance during sessions.

🔧

toolsA comma separated list of tools this agent can access. Use <code>Read, Grep, Glob</code> for read only agents (reviewers, analysts). Add <code>Write, Edit, Bash</code> for agents that make changes. Restricting tools prevents the agent from doing things outside its role.