[BUG] Please reopen #6377 ("Frontmatter Parsing Error: Missing 'name' Field Despite Valid YAML")

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/6377
2. https://github.com/anthropics/claude-code/issues/11205
3. https://github.com/anthropics/claude-code/issues/16916

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Asked Claude Code about it (unedited except for line wraps for readability):

Explain to me why the /doctor command is incorrectly marking ALL agent
definitions in @agents/ as "Missing required "name" field in frontmatter".
⎿  Listed directory agents/

● Let me read the agent definition files to understand their structure.

● Read(agents/code-reviewer.md)
⎿  Read 245 lines

● Read(agents/python-pro-coder.md)
⎿  Read 247 lines

● The agent definition files have valid YAML frontmatter with name fields. The
/doctor command is incorrectly flagging them. Let me search for the /doctor
command implementation to understand why.

● Explore(Find /doctor command code)
⎿  Done (25 tool uses · 64.6k tokens · 2m 27s)

● The /doctor command incorrectly flags your agent files due to a known bug in
Claude Code (Issue #6377 and many duplicates).

Summary

Your agent files are correctly formatted—they have valid YAML frontmatter with
name fields. The problem is in Claude Code's validation logic.

Root Cause

The /doctor command has a frontmatter parsing bug that affects many users
(especially on Linux in VSCode terminal). The validation fails to parse valid
YAML frontmatter and reports "Missing required 'name' field" even when the
field exists.

GitHub tracked this at Issue #6377, which was closed as "NOT_PLANNED" with 10+
duplicate reports (#6709, #6868, #6869, #6950, #7280, #7281, #7303, #7448,
#7794, #7850).

Verification

Your files are correct:

• code-reviewer.md line 2: name: code-reviewer ✓
• python-pro-coder.md line 2: name: python-pro-coder ✓

Both have:

• --- on line 1 (no preceding blank lines)
• Proper YAML indentation with spaces
• Closing --- before markdown content

Workarounds

1. Check for hidden characters:

cat -A agents/code-reviewer.md | head -5

1. Look for unexpected ^I (tabs) or ^M (carriage returns)
2. Verify UTF-8 encoding:

file -bi agents/code-reviewer.md

1. Should output: text/plain; charset=utf-8
2. Ignore the warning: The agents work despite the validation error

Assumption

The bug is in Claude Code's compiled CLI, not your files. The validation code
(obfuscated in cli.js) has parsing issues that haven't been fixed.

Tests as suggested by C-C:

cat -A agents/code-reviewer.md | head -5
---$
name: code-reviewer$
description: Python code review specialist focusing on security, performance, and$
  maintainability. Use when reviewing significant code changes (>100 lines), before$
  PR merges, or when user requests code review.$

file -bi agents/code-reviewer.md
text/plain; charset=us-ascii

I note with interest that CC says "Ignore the warning: The agents work despite the validation error"

Sus, but I'll try it and see if they work.

Works 🎉

❯ Use the Task tool to invoke code-reviewer

● Task(Invoke code-reviewer agent)
  ⎿  Done (0 tool uses · 16.0k tokens · 9s)


● The code-reviewer agent has been invoked and is ready. It can analyze Python code for:

  - Security: Injection vulnerabilities, credential exposure, unsafe deserialization, weak crypto
  - Performance: Inefficient algorithms, N+1 queries, memory leaks, blocking I/O
  - Maintainability: Type hints, error handling, code duplication, SOLID principles

  Provide the code or file path you want reviewed.

This indicates to me that #11205 is not a dupe.

I have no : in description frontmatter, so my guess would be that #16916 is not a dupe.

As mentioned at the outset, this IS a dupe of #6377, but #6377 never should have been closed.

I noticed this as well in the 2.1.3 release, because the agents DO NOT DISPLAY when I type /agents, and I receive this error for 7 of my 19 custom agents when I run /doctor.

The issue DOES NOT OCCUR in 2.0.76, and all of my agents appear as expected. This is a regression in the 2.1 branch.

Any solution to this?

The only way I was able to workaround it was by deleting and re-creating the problematic sub-agents. I still don't know what in the agent config was causing the issue, but that workaround resolved it.

It is looks like that bug is related to UTF-8 BOM. In default mode VS Code use that format for md files.

Root Cause: Session-Level Caching

I tracked this down and found the actual root cause: Claude Code caches agent file parse results at session startup. The /doctor command reads from this in-memory cache, not from disk.

This means:

1. If your agent files have any YAML issue when Claude Code starts, it caches the parse failure
2. Fixing the YAML within the same session does nothing — /doctor keeps reporting the error from cache
3. The only fix is to restart Claude Code (exit and start a new session) after correcting the YAML

This also explains why the "delete and recreate" workaround reported by @shssoichiro works — it likely involved restarting Claude Code between the delete and recreate steps, which reset the cache.

Steps to fix:

1. Fix your agent file YAML (ensure valid frontmatter with name field)
2. Exit Claude Code completely (/exit or Ctrl+C)
3. Start a new session
4. Run /doctor — agents should now parse correctly

The confusing part is that /doctor is supposed to be a diagnostic tool, but by reading from cache instead of re-parsing from disk, it gives stale results that make you think your fix didn't work.

I don't believe your AI-generated diagnosis is accurate. The name field _is_ valid in all of the configurations, as far as users can see. This also would not explain why the issue was not present in 2.0.76, despite no changes being made to the agent configs.

I thought the UTF-8 BOM idea was reasonable, but I went back and checked my files before and after (since I keep them in git), and all of them were saved as UTF-8 without BOM both before and after.

I did some more experimenting, however, and it seems to be related to certain characters in the description field which break parsing in Claude Code 2.1.x but not in 2.0.76. Any description which contains certain characters (I haven't narrowed down a full list, but some seem to include " and \n) must be fully enclosed in quotation marks and have the problematic characters escaped with a preceding \. I'll also note that these agents were all generated using Claude Code, so it is problematic that a future Claude Code update broke parsing of agents generated by an earlier version.

I don't believe your AI-generated diagnosis is accurate. The name field _is_ valid in all of the configurations, as far as users can see. This also would not explain why the issue was not present in 2.0.76, despite no changes being made to the agent configs. I thought the UTF-8 BOM idea was reasonable, but I went back and checked my files before and after (since I keep them in git), and all of them were saved as UTF-8 without BOM both before and after. I did some more experimenting, however, and it seems to be related to certain characters in the description field which break parsing in Claude Code 2.1.x but not in 2.0.76. Any description which contains certain characters (I haven't narrowed down a full list, but some seem to include " and \n) must be fully enclosed in quotation marks and have the problematic characters escaped with a preceding \. I'll also note that these agents were all generated using Claude Code, so it is problematic that a future Claude Code update broke parsing of agents generated by an earlier version.

Well, I got it fixed! Just sharing what did the trick for me.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.