Skill descriptions using YAML multi-line literal block syntax (`|`) are not parsed correctly

Resolved 💬 3 comments Opened Dec 3, 2025 by alexey-pelykh Closed Dec 7, 2025

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

  1. 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
  1. Start a new Claude Code session
  1. Ask Claude to list available skills with descriptions:
claude -p "List all available skills with their descriptions"
  1. 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.

View original on GitHub ↗

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