[BUG] Claude misinterprets skill "description" field using block scalar style

Resolved 💬 4 comments Opened Oct 29, 2025 by seh Closed Jan 12, 2026

Preflight Checklist

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

What's Wrong?

If you create a _skill_ in a _SKILL.md_ file under a _~/.claude/skills/<skill name>_ directory and write a YAML document in the Markdown frontmatter, the YAML "description" field is itself a Markdown document that Claude reads to help it decide when to use the skill. If that "description" field uses the "flow scalar style", Claude interprets it as expected. However, the field instead uses the "block scalar style", Claude misinterprets the value as, say, "|" for the "literal style".

Compare these two _SKILL.md_ files:

  • Flow Style Scalar
---
name: My Skill
description: "Use when ..."
---
# My Skill
...
  • Block Style Scalar
---
name: My Skill
description: |
  Use when ...
---
# My Skill
...

For the latter _SKILL.md_ file, Claude's "available_skills" field for its _Skill_ tool has a "description" element as follows:

<description>
  | (project, gitignored)
</description>

That shows that Claude is failing to parse the Markdown frontmatter as YAML properly.

What Should Happen?

Claude should parse the Markdown frontmatter as a YAML document with a full-featured parser that understands the block scalar style.

Error Messages/Logs

Steps to Reproduce

  1. Create a directory named _~/.claude/skills/my-skill_, and within write a file named _SKILL.md_ with the following content:

```markdown
---
name: My Skill
description: |
Use when ...
---

My Skill

...

2. Start the _claude_ program, and probe it for which _skills_ it knows. Ask it to divulge the _Skill_ tool's "available_skills" list.
3. Inspect the "description" element in the XML document, and note that it lacks the YAML "description" field's intended value, and instead just contains the YAML literal style indicator (`|`).

### Claude Model

Sonnet (default)

### Is this a regression?

No, this never worked

### Last Working Version

_No response_

### Claude Code Version

2.0.22 (Claude Code)

### Platform

Google Vertex AI

### Operating System

macOS

### Terminal/Shell

Other

### Additional Information

Issue #9928 may be related, at least in the reported symptoms.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗