Skip to content

[Skill] SKILL.md frontmatter block scalars (description: | / >) are stored with a literal leading "|"Β #15945

Closed

Description

@blackrose28

Describe the bug

SkillZipParser reads the SKILL.md frontmatter with a hand-written line parser rather than a YAML parser. A valid YAML block scalar such as description: | or description: > is therefore not understood: the literal indicator (| / >) is kept as the first characters of the value, and the indented lines are appended to it.

Expected behavior

For this SKILL.md

---
name: demo
description: |
  First line of the description.
  Second line.
---

# Demo

the skill description should be First line of the description. Second line. (or the literal-style value with newlines), exactly as any YAML parser reads it. Block scalars are the usual way to write a long frontmatter description, and other Agent Skill tooling accepts them.

Actually behavior

The description is stored as | First line of the description. Second line. β€” with a leading | . It shows up that way in the skill list, in the version detail and in the draft version metadata.

A second effect of the same code path: every continuation line that contains a : is also stored as a bogus nested key, because indented lines are treated as one-level nested maps. A description such as

description: |
  Covers the `messages` array shape: shared by both.

produces an extra entry description.Covers the messages array shape in the parsed map. On real skills with long descriptions we saw 4 to 6 parsed keys instead of 2.

How to Reproduce

  1. Create a ZIP containing demo/SKILL.md with the content above.
  2. Upload it through POST /v3/admin/ai/skills/upload (or the console upload).
  3. Read the skill back (GET /v3/admin/ai/skills) and look at description.

The same result is visible without a server by calling SkillZipParser.parseYamlFrontMatterFromMarkdown(skillMd) with that content and printing get("description").

Where

parseYamlFrontMatter and parseYamlScalarValue in
SkillZipParser.java.
The relevant logic is that a line starting with whitespace is appended to currentValue (currentValue.append(' ')) and nothing handles the | / > (or |-, >+, ...) indicators on the key line. The two functions are identical in 3.2.1, 3.2.4 and in develop / 3.3.0-RC, so upgrading does not help.

Suggested fix

Either parse the frontmatter with a real YAML parser (SnakeYAML is already used elsewhere in the project), or at minimum recognise the block scalar indicators on the key line and fold or keep the following indented lines without the indicator, and stop treating those continuation lines as nested keys.

A unit test with description: |, description: > and a continuation line containing : would cover it.

Desktop (please complete the following information):

  • OS: Linux (container)
  • Version: nacos-server v3.2.1-2026.03.30 (code checked unchanged in 3.2.4 and 3.3.0-RC)
  • Module: ai (Skill)
  • SDK: nacos-maintainer-client uploadSkillFromZip

Additional context

Related but different: #15201 (skill meta description not synchronised after uploading a new version). Both concern how the frontmatter description reaches the stored metadata. As a downstream workaround we currently rewrite block-scalar descriptions into one quoted line before calling uploadSkillFromZip, which Nacos reads correctly.

Activity

  1. Ajax-1 commented on Oct 27, 2026

    @Ajax-1
    Contributor

    /assign

    I'd like to work on this. Plan: in SkillZipParser.parseYamlFrontMatter, recognise block-scalar indicators (|, >, with -/+ chomping) on the key line, collect the following indented lines as the value (literal keeps newlines, folded joins with spaces), and stop treating those continuation lines as nested key.sub entries. Plain one-level nested maps like metadata:\n version: 1.0.0 keep working. I'll add unit tests for description: |, description: >, and a continuation line containing : .

  2. KomachiSion commented on Oct 27, 2026

    @KomachiSion
    Collaborator

    Yes, I found this problem yesterday . Thanks for submit issue, we will try to fix it in 3.3.0

  3. added this to the 3.3.0 milestone on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/Skillkind/bugCategory issues or prs related to bug.

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions