[BUG] Four shipped plugin agents fail YAML frontmatter parsing and load as placeholders or not at all #91871

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Four agent files that ship in this repository have frontmatter that Claude Code 2.1.259 cannot parse:

• plugins/plugin-dev/agents/agent-creator.md
• plugins/plugin-dev/agents/plugin-validator.md
• plugins/plugin-dev/agents/skill-reviewer.md
• plugins/pr-review-toolkit/agents/code-simplifier.md

Their description: value spans several lines, the continuation lines (<example>, Context:, user:, ...) are not indented, and the first line ends in Examples:. What happens depends on how the file is loaded:

• As a plugin (claude --plugin-dir plugins/plugin-dev): the debug log says Failed to parse YAML frontmatter, and the agent is registered anyway with the placeholder description Agent from plugin-dev plugin. The agent roster handed to the model then reads plugin-dev:agent-creator: Agent from plugin-dev plugin (Tools: All tools) with none of the triggering examples, so the model has nothing to trigger on.
• Copied to .claude/agents/: the log says YAML frontmatter in <file> failed to parse and was ignored, and the agent is absent from the roster.

The other 11 agent files under plugins/*/agents/ load, and the model receives their descriptions verbatim.

Three properties of the current shape are each fatal on their own (measured with single-variable mutants of agent-creator.md): a plain value that ends in :; continuation lines that are not indented; and : inside indented continuation lines (Context: ...). The only forms that survive are block scalars (description: |-) or a quoted string.

The same shape is what plugins/plugin-dev/skills/agent-development/SKILL.md (Complete Format, Minimal Agent), its examples and references, and agent-creator's own system prompt teach, so agents generated with the plugin inherit the defect. validate-agent.sh never parses YAML, so it passes these files; the extractors proposed in #89404 and #76985 also accept the shape.

What Should Happen?

The four agents load with their full descriptions and <example> blocks on both paths. At minimum, a frontmatter parse failure in a shipped plugin agent should be visible without --debug instead of silently registering a placeholder.

Error Messages/Logs

# .claude/agents/ path (claude -p --debug)
[ERROR] YAML frontmatter in <dir>/.claude/agents/agent-creator.md failed to parse and was ignored: YAML Parse error: Unexpected token
[ERROR] YAML frontmatter in <dir>/.claude/agents/plugin-validator.md failed to parse and was ignored: YAML Parse error: Unexpected token
[ERROR] YAML frontmatter in <dir>/.claude/agents/skill-reviewer.md failed to parse and was ignored: YAML Parse error: Unexpected token
[ERROR] YAML frontmatter in <dir>/.claude/agents/code-simplifier.md failed to parse and was ignored: YAML Parse error: Unexpected token

# plugin path (claude -p --debug --plugin-dir plugins/plugin-dev)
[WARN] Failed to parse YAML frontmatter in <repo>/plugins/plugin-dev/agents/agent-creator.md: YAML Parse error: Unexpected token
[WARN] Failed to parse YAML frontmatter in <repo>/plugins/plugin-dev/agents/plugin-validator.md: YAML Parse error: Unexpected token
[WARN] Failed to parse YAML frontmatter in <repo>/plugins/plugin-dev/agents/skill-reviewer.md: YAML Parse error: Unexpected token

Steps to Reproduce

1. Clone the repository and copy the plugin-dev agents into a fresh project:

   git clone --depth 1 https://github.com/anthropics/claude-code
   mkdir -p /tmp/agents-probe/.claude/agents
   cp claude-code/plugins/plugin-dev/agents/*.md /tmp/agents-probe/.claude/agents/

2. Start a one-turn session there with the debug log on:

   cd /tmp/agents-probe
   claude -p --debug --debug-file /tmp/loader.log --max-turns 1 "hi" >/dev/null
   grep -c 'failed to parse and was ignored' /tmp/loader.log    # prints 3

3. Repeat on the plugin path from an empty directory:

   mkdir -p /tmp/empty && cd /tmp/empty
   claude -p --debug --debug-file /tmp/plug.log --plugin-dir /path/to/claude-code/plugins/plugin-dev --max-turns 1 "List the agent types available to you, verbatim."
   grep 'Failed to parse YAML frontmatter' /tmp/plug.log         # 3 lines

   The model's answer lists the three plugin-dev agents with the placeholder text Agent from plugin-dev plugin and no examples.
4. Convert one file's description to description: |- with every line indented by two spaces and repeat: the log line disappears and the agent's full description reaches the model.

Claude Model

Other

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.259 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Non-interactive/CI environment

Additional Information

• The roster observations above were taken from the request body sent to the model (a local stand-in for the API endpoint), not from the model's own account of itself. Interactive mode was not measured; claude -p was.
• The bug is in file loading, before any model is called, so the Claude Model field does not apply.
• The fix is on the branch fix/agent-description-block-scalars of konsta95/claude-code: compare view against main, commit e830ff6. It converts the four files to description: |- (text unchanged), updates the skill docs and agent-creator's template to teach that form, and changes validate-agent.sh to reject the three fatal shapes, with a regression test. Pull request creation is restricted to collaborators on this repository, so a maintainer would need to pull the branch.
• Related: validate-agent.sh exits 1 on plugin-dev's own agent files and aborts at the first warning #83803 (origin of validate-agent.sh: don't abort at the first warning (set -e + ((x++))) and stop false-flagging valid agents #89404), validate-agent.sh: don't abort at the first warning (set -e + ((x++))) and stop false-flagging valid agents #89404, fix(plugin-dev): read full multi-line description in validate-agent.sh #76985, fix(plugin-dev): parse block scalar agent descriptions #85323, fix(plugin-dev): prevent validate-agent.sh exiting on first warning #84427, fix(plugin-dev): validator scripts abort on first finding due to set -e #66416 all change validate-agent.sh; none changes the agent files.