I run Claude Code as five separate subagents with different permissions —
architect, coder, reviewer, conflict resolver, UI designer. One of them stopped
.
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 --- isnot line 1 |
Read as having no frontmatter, so documentation again |
A name starting with- , or containing: |
The whole file is skipped |
A name but nodescription |
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
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
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
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
The version that adds a UI Designer persona, review criteria, a per-Issue
parallel execution script and a 11-chapter guide is on the
The full kit — five personas, the scripts and the complete guide — is available here.