Repository navigation
Description
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.
---
# Demothe 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
- Create a ZIP containing
demo/SKILL.mdwith the content above. - Upload it through
POST /v3/admin/ai/skills/upload(or the console upload). - Read the skill back (
GET /v3/admin/ai/skills) and look atdescription.
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
Ajax-1 commentedon Oct 27, 2026
/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 nestedkey.subentries. Plain one-level nested maps likemetadata:\n version: 1.0.0keep working. I'll add unit tests fordescription: |,description: >, and a continuation line containing:.KomachiSion commentedon Oct 27, 2026
Yes, I found this problem yesterday . Thanks for submit issue, we will try to fix it in 3.3.0