XML example tags in agent frontmatter silently break agent loading
Bug
Custom agents in .claude/agents/ that include Examples: with <example> XML tags inside the YAML frontmatter (between --- delimiters) fail to load silently — they don't appear in /agents and can't be used as subagent_type in the Agent tool. No error is shown anywhere.
Reproduction
- Create
.claude/agents/my-agent.mdwith<example>tags in the frontmatter:
---
name: my-agent
description: Does something useful.
Examples:
<example>
user: "Do the thing"
assistant: "I'll use my-agent to do the thing."
</example>
model: sonnet
---
You are an expert at doing the thing.
- Start a new Claude Code session
- Run
/agents—my-agentis not listed - Try
subagent_type: "my-agent"— fails with "Agent type not found"
Expected behavior
The agent should load successfully, or if the frontmatter is invalid, an error/warning should be shown.
Workaround
Move the examples from the frontmatter into the markdown body (after the closing ---):
---
name: my-agent
description: Does something useful.
model: sonnet
---
## When to Use
<example>
user: "Do the thing"
assistant: "I'll use my-agent to do the thing."
</example>
You are an expert at doing the thing.
Impact
This affected 4 out of 5 of my custom agents. The failure is silent — no error message, no warning — so it took significant debugging to identify the cause. The <example> tag format is used in Claude Code's own documentation, which makes it easy to put them in the frontmatter where they break YAML parsing.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗