XML example tags in agent frontmatter silently break agent loading

Resolved 💬 3 comments Opened Apr 9, 2026 by noa-weiss Closed Apr 13, 2026

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

  1. Create .claude/agents/my-agent.md with <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.
  1. Start a new Claude Code session
  2. Run /agentsmy-agent is not listed
  3. 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.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗