Skill descriptions using YAML multi-line literal block syntax (`|`) are not parsed correctly
Bug Description
Skill descriptions in SKILL.md files that use YAML multi-line literal block syntax (description: |) are not correctly parsed. Instead of extracting the multi-line content, the literal | character is passed through to Claude, resulting in descriptions appearing as | (user) instead of the actual description text.
This breaks model-invoked skill discovery since Claude cannot see the descriptions to decide when to activate skills.
Environment
- Claude Code version: 2.0.57
- Node version: v25.2.1
- OS: macOS Darwin 25.1.0 arm64
Steps to Reproduce
- Create a skill with multi-line YAML description:
---
name: my-skill
description: |
This is a multi-line description.
Use when: doing something specific.
---
# My Skill Content
- Start a new Claude Code session
- Ask Claude to list available skills with descriptions:
claude -p "List all available skills with their descriptions"
- Observe the description for
my-skill
Expected Behavior
Claude should see:
my-skill: This is a multi-line description. Use when: doing something specific. (user)
Actual Behavior
Claude sees:
my-skill: | (user)
The | character is passed through literally, and the actual description content is lost.
Evidence
Tested with 19 skills using description: | syntax - all showed | (user).
After converting to single-line quoted strings, all descriptions became visible:
Before (broken):
description: |
Provide evidence proportional to stakes for all claims. Use when: making assertions...
Result: evidence-reasoning: | (user)
After (working):
description: "Provide evidence proportional to stakes for all claims. Use when: making assertions, declaring completion, presenting findings."
Result: evidence-reasoning: Provide evidence proportional to stakes for all claims. Use when: making assertions, declaring completion, presenting findings. (user)
Workaround
Use single-line quoted strings instead of multi-line block literal syntax:
# ❌ Does not work
description: |
Multi-line description text here.
# ✅ Works correctly
description: "Single-line description text here."
Impact
- Severity: High for skill authors
- Effect: Skills using multi-line descriptions cannot be discovered by Claude
- Scope: Affects all user-defined skills with
|or potentially>YAML syntax
Suggested Fix
The YAML frontmatter parser should correctly handle multi-line literal block (|) and folded block (>) syntax when extracting the description field.
Additional Context
The skills documentation shows examples that may lead users to use multi-line syntax for longer descriptions. Since descriptions can be up to 1024 characters, multi-line formatting would be natural for readability in source files.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗