[BUG] UTF-8 BOM in agent .md silently prevents agent registration (Agent type not found)
Open 💬 0 comments Opened Jul 2, 2026 by Civilten
Summary
A custom agent definition file under ~/.claude/agents/ that starts with a UTF-8 BOM (EF BB BF) is silently skipped during agent registry loading. The agent never appears in the available-agents list, and spawning it via the Agent tool fails with Agent type '<name>' not found. There is no warning or error output — the file is just ignored.
Removing the BOM (no other change) makes the same file register and spawn correctly in the next fresh session.
Environment
- Claude Code 2.1.168
- Windows 11 Pro (10.0.26200)
- Agent file: plain real file (no symlink) at
~/.claude/agents/director.md, valid frontmatter (name,description,tools,model)
Steps to reproduce
- Create a valid agent definition, e.g.
~/.claude/agents/myagent.md, saved with a UTF-8 BOM. (On Windows this happens easily: PowerShell 5.1Out-File/Set-Content -Encoding utf8writes UTF-8 with BOM by default.) - Verify first bytes:
EF BB BF 2D 2D 2D ...instead of2D 2D 2D(---). - Start a fresh Claude Code session.
- Observe the agent is absent from the available agent types;
Agent(subagent_type: "myagent")→Agent type 'myagent' not found. - Strip the BOM (file content otherwise identical), start another fresh session → agent is listed and spawns normally.
Differential evidence
- A neighboring agent file in the same directory whose first bytes are
2D 2D 2D(---) registered fine in the same sessions where the BOM'd file was skipped. - Byte-level diff between "not registered" and "registered" states of the same file: only the 3-byte BOM prefix.
- Symlink/timing causes were ruled out separately (file was a real file created well before session start).
Expected behavior
Either of:
- Strip a leading UTF-8 BOM before frontmatter parsing (accept the file), or
- Emit a visible warning when an
agents/*.mdfile is present but fails frontmatter parsing, instead of silently skipping it.
Related issues (same "silent skip" family)
- #12958 — frontmatter parsing fragility
- #13363 — Write tool BOM handling on Windows
- #55791 — agent/command loader skips file symlinks via
Dirent.isFile()(also silent)
BOM'd markdown is very common on Windows, so this silently breaks custom agents for a whole platform's default tooling.