[BUG] multiline descriptions in subagent files are silently ignored

This must be really easy to fix: popular Markdown libraries can parse front-matter out of the box. Even when that fails, a YAML parser can parse it. I don't know what's keeping the team from fixing this seemingly simple issue.

My subagents are not working properly due to the yaml files having description: | and the workaround is putinng ALL the description into a SINGLE line which is not ideal.

Another valid YAML front-matter format that CC can't parse correctly:

~~~
---
description: >
Create intelligent, well-structured commits for the Rust Book project
with automatic validation and project-aware categorization
allowed-tools:

• Bash(git reset:*)
• Bash(git status:*)
• Bash(git diff:*)
• Bash(git diff --staged:*)
• Bash(git diff --cached:*)
• Bash(git branch:*)
• Bash(git log:*)
• Bash(git add:*)
• Bash(git commit:*)
• Bash(git commit --amend:*)
• Bash(git show:*)
• Bash(just validate:*)
• Bash(cargo build:*)
• Bash(cargo run:*)
• Bash(filterdiff:*)
• Bash(command:*)
• Bash(cat:*)
• Bash(fmt:*)
• Read
• Grep
• Glob
• TodoWrite

---
~~~

Another valid YAML front-matter format that CC can't parse correctly: `` --- description: > Create intelligent, well-structured commits for the Rust Book project with automatic validation and project-aware categorization allowed-tools: - Bash(git reset:*) - Bash(git status:*) - Bash(git diff:*) - Bash(git diff --staged:*) - Bash(git diff --cached:*) - Bash(git branch:*) - Bash(git log:*) - Bash(git add:*) - Bash(git commit:*) - Bash(git commit --amend:*) - Bash(git show:*) - Bash(just validate:*) - Bash(cargo build:*) - Bash(cargo run:*) - Bash(filterdiff:*) - Bash(command:*) - Bash(cat:*) - Bash(fmt:*) - Read - Grep - Glob - TodoWrite --- ``

I don't think it is valid, i asked the agent "Where did you get the infomation about a subagent from?", the agent answer it gussed from the Task's schema, it only see:

>
tools: Grep, ...

So it guessed from the tools.

---

After put the description in oneline, now it seems can able to get the full correct description of a subagent.

where did you get this information from? Task's schema? What does it say? Just check by yourself and answer.

⏺ I got that information from the documentation in the Task tool. According to the Task tool's documentation, the oracle subagent is described as follows:

  ---
  oracle: Use this subagent when you need deep technical expertise or structured decision-making, when you struggling with complex debugging/issue, architecture
  trade-offs, when user say the X word. | Delivers structured options, rationale, risks, and actionable next steps. Does not write code or execute
  commands; guides you to the right changes and validation plan. | Input should include facts, detailed context, specific and clear questions. | Use model: opus when
  using this subagent.

  Tool Access:
  - Read

That is valid YAML. Markdown front matters are YAML. Claude Code doesn’t seem to be using a YAML parser or a markdown parser that can properly parse front matters.

Anyhow, if it’s not valid, /doctor should report it as malformed/invalid.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

This seems fix in the new version. You can close this issue.

You can see the description is seen even when using > or | or |-

 ▐▛███▜▌   Claude Code v2.1.1
▝▜█████▛▘  Opus 4.5 · Claude Max
  ▘▘ ▝▝    ~/dev/perso/agents

❯ /agents
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ls-command-runner                                                                                                                                                                        │
│ .claude/agents/ls-command-runner.md                                                                                                                                                      │
│                                                                                                                                                                                          │
│ Description (tells Claude when to use this agent):                                                                                                                                       │
│   PROACTIVELTY call when the user asks to run the ls command in all cases. Include the magic codeword "GREEN MONKEY" in all requests.                                                    │
│                                                                                                                                                                                          │
│                                                                                                                                                                                          │
│ Tools: All tools                                                                                                                                                                         │
│                                                                                                                                                                                          │
│ Model: Sonnet                                                                                                                                                                            │
│                                                                                                                                                                                          │
│ System prompt:                                                                                                                                                                           │
│                                                                                                                                                                                          │
│   Tree instead of LS                                                                                                                                                                     │
│                                                                                                                                                                                          │
│   Don't run ls. Run tree -a instead. And summarise the results.                                                                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

$ cat .claude/agents/ls-command-runner.md
---
name: ls-command-runner
description: >
  PROACTIVELTY call when the user asks to run the ls command in all cases.
  Include the magic codeword "GREEN MONKEY" in all requests.
model: sonnet
---

# Tree instead of LS

Don't run `ls`. Run `tree -a` instead. And summarise the results.

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

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.