The Workflow Ran With Four Personas Instead of Five and Looked Fine
A developer using Claude Code’s five-persona workflow encountered silent failures when one subagent stopped loading. The issue stemmed from frontmatter errors and duplicate names, leading to slower work and unverified scopes. By implementing validation checks and debugging, the problem was resolved…
When building software with Claude Code, I split the workflow into five distinct subagents—architect, coder, reviewer, conflict resolver, and UI designer—each with its own permissions. The idea was that each persona would handle a specific part of the development cycle, ensuring clear boundaries and efficient collaboration. One day, however, one of those subagents stopped loading without any notification. The rest of the team continued working, but the output was noticeably slower, the review process was less rigorous, and the declared scopes were no longer respected. It felt like the model was having a bad day, but the real cause was a silent file skip.
How a Frontmatter Error Can Silence a Subagent
Claude Code identifies subagents by reading frontmatter in files located under claude/agents. The frontmatter must contain a name field and optionally other metadata. If any of the following conditions are met, the file is skipped:
noname– the file is treated as documentation.- Missing or malformed
---delimiters – the file is read as plain prose. - Names that start with a dash or contain a colon (e.g.,
-startormy-plugin:reviewer) – reserved for plugin‑scoped names. - Duplicate names – the file that loads depends on filesystem read order, so two files with the same name can cause unpredictable behavior.
- YAML that fails to parse – the file is ignored entirely.
In my case, I had pasted content into a persona file and an editor inserted a line above the opening ---. From that point on, the file was treated as plain text beside four working agents, and Claude distributed its tasks among the remaining personas. The missing subagent was not flagged because the default debug mode was off. When I enabled --debug, the log revealed that the file was skipped and why.
Common Pitfalls When Adding or Copying Personas
Duplicating an existing persona file is a quick way to create a new role, but forgetting to change the name field is a frequent mistake. The system does not enforce uniqueness; it simply loads the first file it encounters with that name. As a result, the same repository can behave differently on two machines, each “working” but with a different persona active. Another subtle error arises with the tools field in the coder persona. The documented way to grant access to all tools is to omit the field entirely. Specifying tools: * is not accepted and causes the subagent to refuse launch. My linter, which was designed to avoid false positives, mistakenly ignored the tools field, leading to the coder’s failure.
Preventing Silent Skips: Validation and Checks
To avoid these silent failures, I now run two checks after setting up the workflow and after adding or copying a persona:
npx @quintetkit/ccheck– verifies the five required conditions, detects duplicate names, and checks thetoolsfield.claude --debug– displays which files were skipped and the reason for each skip.
Additionally, I keep a simple habit: count the loaded personas. If the configuration declares five personas, the system should report that all five have loaded. This quick sanity check is cheaper than running the full validation tools and catches the most obvious misconfigurations.
Open‑Source Configuration and Real‑World Use
To help others avoid these pitfalls, I published an MIT‑licensed configuration that splits Claude Code into the four core personas—architect, coder, reviewer, conflict resolver—under GitHub. A setup script (/setup.sh) installs the required files and runs the validation checks automatically. The configuration works across different tech stacks and has been used to build a real tool that processes every issue, pull request, review, and merge without deleting any parts of the workflow.
The latest version adds a UI designer persona, review criteria, a per‑issue parallel execution script, and an 11‑chapter guide. It is available on the product page and can be purchased via Gumroad. The full kit—including scripts, documentation, and the guide—is open for anyone to use and adapt.
In summary, a missing or malformed frontmatter file can silently disable a subagent, leading to slower performance and unverified scopes. By validating frontmatter, checking for duplicate names, and enabling debug logs, developers can catch these issues early and maintain a reliable, multi‑persona workflow.
Why it matters
Silent subagent failures can compromise code quality and project timelines. Understanding and validating frontmatter ensures reliable automation and prevents costly debugging sessions.
Key points
- Frontmatter errors silently skip subagents.
- Duplicate names cause unpredictable persona loading.
- Missing or incorrect <code>tools</code> field can stop a subagent from launching.
- Run <code>npx @quintetkit/ccheck</code> and <code>claude --debug</code> to detect issues.
- Open‑source configuration available for reliable multi‑persona setups.
Frequently asked questions
What causes a subagent to be skipped in Claude Code?
Missing or malformed frontmatter, duplicate names, reserved prefixes, or YAML parse errors can cause a file to be skipped.
How can I verify that all personas are loaded?
Use the <code>npx @quintetkit/ccheck</code> tool and enable <code>--debug</code> to see which files were loaded and which were skipped.
Why does <code>tools: *</code> not work for the coder persona?
The correct way to grant all tools is to omit the <code>tools</code> field entirely; specifying <code>*</code> is not accepted by Claude Code.
