The Workflow Ran With Four Personas Instead of Five and Looked Fine

A developer running Claude Code with five separate subagents — architect, coder, reviewer, conflict resolver, and UI designer — found that one persona silently stopped loading after an editor inserted content above the opening frontmatter delimiter, causing the file to be treated as documentation rather than an agent. Because the failure produces no session warning and only appears in the debug log, the remaining agents absorbed the work, making the degradation look like the model performing poorly rather than a missing configuration. The developer documented five frontmatter conditions that cause silent subagent skips, plus a `tools: *` entry that makes Claude Code refuse to launch a subagent, and released a checker tool, `npx @quintetkit/ccheck`, to detect them.

I run Claude Code as five separate subagents with different permissions — architect, coder, reviewer, conflict resolver, UI designer. One of them stopped loading. Nothing said so. The work still got done, by whoever was left. It got slower, review got softer, declared scopes stopped being respected. Every one of those looks like "the model is having a bad day". The symptom has the shape of not working well . The cause was not being there . .claude/agents/ is skipped silently Five conditions in the frontmatter, any one of which means the file is not treated as a subagent: | Condition | What happens | |---|---| | No name | Treated as documentation — a note kept beside your agents | | The opening --- is not line 1 | Read as having no frontmatter, so documentation again | | A name starting with - , or containing : | The whole file is skipped | | A name but no description | Skipped | | YAML that does not parse | Nothing is read, file skipped | None of these appear in the session. The reason goes to the debug log, which you see with --debug , which you are not running when things seem fine. The second row is the one I hit. I had pasted content into a persona file and an editor put something above the opening --- . From then on the file was prose sitting next to four agents, and Claude distributed its work to them. : is unavailable because it is reserved for plugin-scoped names like my-plugin:reviewer . A leading - is out for the same class of reason. Adding a persona by duplicating an existing one is the obvious move, and forgetting to change name is the obvious mistake. Which of two files with the same name loads is not documented. It is decided by filesystem read order. So the same repository can run a different persona on a different machine , and both machines are "working". I do not have a story about being burned by this one, and I am fairly sure that is luck rather than care. claude plugin validate gets you part of the way claude plugin validate .claude/agents claude plugin validate ~/.claude/agents It finds frontmatter that fails to parse. Two limits worth knowing: name Which is most of the list above. It is worth running and it is not sufficient. My coder persona had this: tools: meaning "this one gets everything". tools accepts exact tool names or the server patterns mcp <server / mcp <server . A bare is not among them , and an entry resolving to nothing makes Claude Code refuse to launch the subagent. The documented way to say "everything" is to omit the field. Why my own linter could not see that is written up separately. https://quintetkit.github.io/en/articles/blind-spot-from-refusing-to-check.html https://quintetkit.github.io/en/articles/blind-spot-from-refusing-to-check.html The short version is that the rule I wrote to avoid false positives was phrased as "don't look at the tools field". That one is worse than a missing persona, because coder is the one that writes the code. The other four keep working, so it presents as the coder being unreliable today. Two checks, and I only run them twice: after setup, and after adding or copying a persona. npx @quintetkit/ccheck the five conditions, duplicate names, tools: claude --debug once, to see what was skipped and why And a habit that is cheaper than either: count them. If the configuration says five personas, the thing you want to confirm is that five loaded — not that the work is getting done. The work getting done was never the question. The five conditions and every frontmatter field, in one table: https://quintetkit.github.io/en/reference/claude-code-subagent-frontmatter.html https://quintetkit.github.io/en/reference/claude-code-subagent-frontmatter.html I publish the configuration for splitting Claude Code into separate personas — Architect, Coder, Reviewer, Conflict Resolver — under MIT. Copy it, run ./setup.sh , and it works. It does not depend on your tech stack. https://github.com/quintetkit/quartet https://github.com/quintetkit/quartet I built one real tool using nothing but this workflow. Every Issue, PR, review and merge is still there. The parts that went wrong were not deleted. https://github.com/quintetkit/mdlinkcheck https://github.com/quintetkit/mdlinkcheck The version that adds a UI Designer persona, review criteria, a per-Issue parallel execution script and a 11-chapter guide is on the product page https://quintetkit.github.io/index.en.html . The full kit — five personas, the scripts and the complete guide — is available here.