[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

  1. Create a valid agent definition, e.g. ~/.claude/agents/myagent.md, saved with a UTF-8 BOM. (On Windows this happens easily: PowerShell 5.1 Out-File/Set-Content -Encoding utf8 writes UTF-8 with BOM by default.)
  2. Verify first bytes: EF BB BF 2D 2D 2D ... instead of 2D 2D 2D (---).
  3. Start a fresh Claude Code session.
  4. Observe the agent is absent from the available agent types; Agent(subagent_type: "myagent")Agent type 'myagent' not found.
  5. 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/*.md file 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.

View original on GitHub ↗