Custom sub-agents intermittently missing from 'Available agent types' despite valid .md files

Summary

A fixed subset of 5 custom sub-agents defined in ~/.claude/agents/*.md intermittently do not appear in the "Available agent types" list injected at session start, while other sub-agents in the exact same directory, with the same frontmatter structure, load correctly every time.

Environment

• Claude Code version: 2.1.206 (bug also reproduced on 2.1.205)
• OS: Windows 10 Pro 10.0.19045
• ~/.claude/agents/ contains 14 custom agent .md files total

Reproduction (4 separate sessions, same result each time)

Missing agents (always the same 5): atlas, bobby, finn, iuris, sage

Present agents (always load fine): aria, cicero, cyrus, kael, lex, luma, radar, rex, vera

Confirmed reproducible across:

• Session #449 (2026-07-09): same 5 missing
• Session #451 (2026-07-10): same 5 missing, ran /doctor — found no local cause (settings.json/settings.local.json clean, no disabledAgents, no blocklist entries, install healthy, single native install)
• Session #452 (2026-07-10): same 5 missing again; as an experiment, deleted and rewrote all 5 .md files with byte-identical content (verified via diff) to rule out a stale-registration/cache issue
• Current session (2026-07-10, fresh session after full restart): same 5 still missing, even after the file recreation from session #452

What we ruled out

• Encoding/BOM: identical across missing vs. working files (UTF-8, CRLF, no BOM)
• Frontmatter YAML: valid, same structure (name/description/tools/model) as the 9 working agents
• settings.json / settings.local.json: no agent allowlist/blocklist, no disabledAgents
• plugins/blocklist.json: only 2 unrelated test entries (code-review, fizz)
• Name collision with plugins/commands/skills: none found
• Stale cache (stats-cache.json, cache/): no agent list cached there
• /doctor: ran clean, reported no issues with the installation or config
• File recreation (delete + rewrite with identical content): no effect — same 5 agents still missing in the next fresh session

Direct test this session

Invoking the agent directly confirms it's genuinely not registered, not just hidden from a listing:

Agent type 'atlas' not found. Available agents: aria, cicero, claude, claude-code-guide, claude-seo:seo-backlinks, claude-seo:seo-content, claude-seo:seo-dataforseo, claude-seo:seo-geo, claude-seo:seo-google, claude-seo:seo-image-gen, claude-seo:seo-local, claude-seo:seo-maps, claude-seo:seo-performance, claude-seo:seo-schema, claude-seo:seo-sitemap, claude-seo:seo-technical, claude-seo:seo-visual, cyrus, Explore, general-purpose, kael, lex, luma, Plan, radar, rex, statusline-setup, vera

Notes / possible lead

One theory we tested and discarded: we noticed the working agent radar.md had Birth time == Modify time == today (i.e. it had been rewritten from scratch, not edited in-place) and hypothesized that a full rewrite was the trigger for registration. This turned out to be a red herring — radar.md's recent birth time was a side effect of an unrelated content fix (it was missing the Skill tool in its frontmatter). The file-recreation experiment in session #452, done specifically to test this theory on the 5 broken agents, had no effect.

We have not been able to identify any difference between the 5 broken agent files and the 9 working ones other than file content itself (names, descriptions, tool lists). This points to either:

• A limit on the number of custom agents loaded/registered (14 total defined, 9 load, 5 don't — consistently the same 5, not random)
• A parsing/registration bug tied to something in the specific content of these 5 files that isn't YAML-frontmatter validity
• A scan-order or race condition in the agent directory scan at session boot

Expected behavior

All 14 valid custom agent .md files in ~/.claude/agents/ should appear in "Available agent types" every session, or the CLI should surface an error/warning explaining why a given file was skipped.

Actual behavior

The same 5 of 14 agents are silently omitted from the list across 4 independent sessions over 2 days, with no error or warning, and recreating the files from scratch does not fix it.