Silent Config Errors Can Drop Claude Code Subagents Without Any Warning
A developer running Claude Code with five role-based subagents discovered that one persona had been silently skipped, leaving the workflow operating with only four agents undetected. The missing agent was caused by a configuration file whose frontmatter did not start on the first line, one of five conditions that cause Claude Code to silently ignore an agent file. Other triggers include a missing agent name, unparseable YAML, or a name containing reserved characters like colons or leading hyphens. These failures do not surface in normal sessions and only appear in debug logs, which most users do not enable when things appear to be working. The developer now recommends running a dedicated config checker and the debug flag after initial setup and after any changes to agent files, alongside a simple habit of counting active personas to catch discrepancies early.
This is an AI-generated summary. ShortSingh links to the original source for the complete article.

Discussion (0)
Log in to join the discussion and vote.
Log in