TL;DR — Claude Code's description field is not a human-readable summary. It's the routing signal the dispatcher reads to decide whether to invoke your subagent. Write it like documentation and your agent never fires. Write it in trigger phrases and it runs when it should.
The agent that sat there doing nothing
I wrote a subagent I was proud of. Solid instructions, tight scope, the works. Dropped it in ~/.claude/agents/, opened a project, did exactly the kind of task it was built for — and nothing happened. Claude just did the work itself, inline, ignoring the agent entirely.
I assumed I'd misconfigured something. I hadn't. The agent was fine. The problem was the one field I'd treated as an afterthought: the description. I'd written it the way you'd write a README line:
description: An expert code reviewer that analyzes your code for quality and bugs.
