[BUG] Agent .md without `name:` in frontmatter is silently skipped: no warning, "Agent type not found" is the only signal

What's Wrong?

An agent definition in .claude/agents/*.md whose frontmatter has description: but no name: is silently dropped at load. The name is not inferred from the filename. Nothing is reported: no startup warning, no /doctor finding, nothing on stderr. The only symptom comes later, when something tries to use the agent: Agent type '<x>' not found from the Agent tool, or --agent '<x>' not found from the CLI.

Impact in practice: we had 20 project agents, 19 of them generated from a template that left out name:. All 19 were unreachable for about 11 weeks and nobody noticed. The first theory was that the model just wasn't choosing to dispatch them, and that nearly led to "fixing" the prompt instead of the files. The only evidence in transcripts was the Agent type not found errors.

What Should Happen?

Any of these would have caught it immediately:

1. Infer name from the filename (as skills do), or
2. A startup / /doctor / /agents warning listing agent files that were skipped, with the reason (missing required field: name), or
3. The Agent type '<x>' not found error mentioning that a file .claude/agents/<x>.md exists but was rejected, and why.

The same reporting would also cover the BOM (#73158), hooks: [] (#91781) and missing-description (#50522) cases.

Steps to Reproduce

mkdir -p repro/.claude/agents && cd repro
printf -- '---\nname: has-name\ndescription: Probe agent with name\n---\nSay hi.\n' > .claude/agents/has-name.md
printf -- '---\ndescription: Probe agent without name\n---\nSay hi.\n'            > .claude/agents/no-name.md
claude -p --agent no-name  "reply ok"
claude -p --agent has-name "reply ok"

Observed on 2.1.281:

--agent 'no-name' not found. Available agents: claude, Explore, general-purpose, has-name, Plan, statusline-setup, ...

(exit code 0, no other output) while --agent has-name works. The same happens in-session through the Agent tool (Agent type 'no-name' not found).

Claude Code Version

2.1.281 (Claude Code)

Platform / OS

Anthropic API · Linux (Debian-based container) · bash

Is this a regression?

Unknown. #50522 reports the equivalent missing-description behaviour on 2.1.114.

Additional Information

Also noticed while reproducing: claude -p --agent <missing> exits 0 after printing the not-found message, so scripts can't detect the failure. It might be worth fixing in the same change.

Related

#50522 (closed/locked, same class of bug for a missing description:), #73158 (BOM), #91781 (hooks: []), #82361 / #90568 / #93171 (agents missing from the registry for unclear reasons), #93109 (unknown frontmatter keys silently ignored).