Skip to content

YAML Frontmatter Parsing — Folded Scalars and Multi-Line Block Literals

Problem

YAML frontmatter in SKILL.md files uses three description styles:

  1. Simple inline: description: short text
  2. Folded scalar: description: > or description: >- followed by indented text
  3. Block literal: description: | followed by indented text (multi-line)

A naive awk extractor that matches ^description: and takes everything after the : returns > or >- as the value for folded scalars, and only the first continuation line for block literals.

# BAD: returns ">" for folded scalars
/^description:/ { desc = substr($0, index($0, ":") + 2) }

Solution

Extend the awk extractor to detect folded/block indicator values and read continuation lines:

/^description:/ {
  val = substr($0, index($0, ":") + 2)
  # Strip leading/trailing whitespace
  gsub(/^[[:space:]]+|[[:space:]]+$/, "", val)

  if (val == ">" || val == ">-" || val == ">+" || val == "|" || val == "|-" || val == "|+") {
    # Multi-line: collect all indented continuation lines
    desc = ""
    while ((getline line) > 0) {
      if (line ~ /^[[:space:]]/) {
        # Continuation line — strip leading indent and append
        gsub(/^[[:space:]]+/, "", line)
        gsub(/[[:space:]]+$/, "", line)
        if (desc == "") desc = line
        else desc = desc " " line
      } else {
        # Reached next key — push back and break
        # (awk has no ungetline; set a flag or handle via next-key detection)
        break
      }
    }
  } else {
    desc = val
  }
}

For folded scalars (>), join continuation lines with a space. For block literals (|), join with a space for table/JSON output (newlines don't render in table cells).

Prevention

  • Test fixtures must include folded and block scalar examples. A test suite using only description: simple text fixtures will not catch these bugs.
  • At minimum, add one description: > and one description: | case to the test SKILL.md fixtures.
  • Add an explicit assertion: grep "vt-c-claudemd-evolve" output.md | grep -v ">" to catch the literal > regression.
  • SPEC-125 review finding DOC-1 (Medium) and DOC-2 (Low)
  • Fix commit: dfa6206f fix(SPEC-125): handle YAML folded scalars and multi-line descriptions