Why Your Claude Code Subagents Fail: Description, Name Conflicts, and Bad Tool Entries
Claude Code allows developers to create custom subagents using Markdown files with YAML frontmatter, stored in either a project-level or global agents directory. The routing system works entirely through the description field — Claude reads each subagent's description and decides when to delegate based on how well it matches a given task. Vague, title-like descriptions are the most common reason subagents go unused, while detailed descriptions that specify when to delegate work far more reliably. Two additional failure points include name collisions that silently drop a file and invalid tool entries that prevent the subagent from launching altogether. Optional fields such as model, maxTurns, memory, and isolation offer further control over how each subagent behaves and executes.
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