[Bug]: Improve skill YAML frontmatter parsing tolerance for unquoted colons in scalar values

[hexly666]

AgentScope-Java is an open-source project. To involve a broader community, we recommend asking your questions in English.

Describe the bug

When loading a skill via FileSystemSkillRepository, the MarkdownSkillParser fails to parse YAML frontmatter if the description field contains unquoted : (colon followed by space) patterns. SnakeYAML interprets : as a key-value separator, causing a ScannerException.

To Reproduce
When loading a skill via FileSystemSkillRepository, the MarkdownSkillParser fails to parse YAML frontmatter if the description field contains unquoted : (colon followed by space) patterns. SnakeYAML interprets : as a key-value separator, causing a ScannerException.

Example problematic SKILL.md:

---
name: testskils
description: 测试skills, node: 无法找到EDI Partner、EDI Partner不存在、Partner配置错误、850订单没有生成SO、850订单报错、Can't find the EDI Customer setup in the EDI partner function、查不到850订单。处理EDI 850订单中无法找到EDI Partner的问题，当850报错包含Can't find the EDI Customer setup in the EDI partner function时使用此skill。
---
# Skill Content

**Expected behavior**
A clear and concise description of what you expected to happen.

**Error messages**
Detailed error messages.

**Environment (please complete the following information):**

- AgentScope-Java Version:  1.0.12
- Java Version: 21
- OS: macos

**Additional context**
org.yaml.snakeyaml.scanner.ScannerException: mapping values are not allowed here
 in 'string', line 2, column 28:
 description: 测试skills, node: 无法找到EDI Partner、EDI Partner不存在 ... 
 ^

 at org.yaml.snakeyaml.scanner.ScannerImpl.fetchValue(ScannerImpl.java:917)
 at org.yaml.snakeyaml.scanner.ScannerImpl.fetchMoreTokens(ScannerImpl.java:406)
 at org.yaml.snakeyaml.scanner.ScannerImpl.checkToken(ScannerImpl.java:239)
 at org.yaml.snakeyaml.parser.ParserImpl$ParseBlockMappingKey.produce(ParserImpl.java:637)
 at org.yaml.snakeyaml.parser.ParserImpl.peekEvent(ParserImpl.java:161)
 at org.yaml.snakeyaml.comments.CommentEventsCollector$1.peek(CommentEventsCollector.java:57)
 at org.yaml.snakeyaml.comments.CommentEventsCollector$1.peek(CommentEventsCollector.java:43)
 at org.yaml.snakeyaml.comments.CommentEventsCollector.collectEvents(CommentEventsCollector.java:136)
 at org.yaml.snakeyaml.comments.CommentEventsCollector.collectEvents(CommentEventsCollector.java:116)
 at org.yaml.snakeyaml.composer.Composer.composeScalarNode(Composer.java:249)
 at org.yaml.snakeyaml.composer.Composer.composeNode(Composer.java:214)
 at org.yaml.snakeyaml.composer.Composer.composeValueNode(Composer.java:396)
 at org.yaml.snakeyaml.composer.Composer.composeMappingChildren(Composer.java:361)
 at org.yaml.snakeyaml.composer.Composer.composeMappingNode(Composer.java:329)
 at org.yaml.snakeyaml.composer.Composer.composeNode(Composer.java:218)
 at org.yaml.snakeyaml.composer.Composer.getNode(Composer.java:141)
 at org.yaml.snakeyaml.composer.Composer.getSingleNode(Composer.java:167)
 at org.yaml.snakeyaml.constructor.BaseConstructor.getSingleData(BaseConstructor.java:179)
 at org.yaml.snakeyaml.Yaml.loadFromReader(Yaml.java:508)
 at org.yaml.snakeyaml.Yaml.load(Yaml.java:437)
 at io.agentscope.core.skill.util.MarkdownSkillParser.parseYamlMetadata(MarkdownSkillParser.java:155)
 at io.agentscope.core.skill.util.MarkdownSkillParser.parse(MarkdownSkillParser.java:113)
 at io.agentscope.core.skill.util.SkillUtil.createFrom(SkillUtil.java:91)
 at io.agentscope.core.skill.util.SkillFileSystemHelper.loadSkillFromDirectory(SkillFileSystemHelper.java:98)
 at io.agentscope.core.skill.util.SkillFileSystemHelper.lambda$getAllSkills$4(SkillFileSystemHelper.java:145)
 at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.accept(ForEachOps.java:184)
 at java.base/java.util.stream.ReferencePipeline$2$1.accept(ReferencePipeline.java:179)
 at java.base/java.util.Iterator.forEachRemaining(Iterator.java:133)
 at java.base/java.util.Spliterators$IteratorSpliterator.forEachRemaining(Spliterators.java:1939)
 at java.base/java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:509)
 at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:499)
 at java.base/java.util.stream.ForEachOps$ForEachOp.evaluateSequential(ForEachOps.java:151)
 at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.evaluateSequential(ForEachOps.java:174)
 at java.base/java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
 at java.base/java.util.stream.ReferencePipeline.forEach(ReferencePipeline.java:596)
 at io.agentscope.core.skill.util.SkillFileSystemHelper.getAllSkills(SkillFileSystemHelper.java:141)
 at io.agentscope.core.skill.repository.FileSystemSkillRepository.getAllSkills(FileSystemSkillRepository.java:119)

[hexly666]

In MarkdownSkillParser.java (line 145–183), the parseYamlMetadata method delegates directly to SnakeYAML's SafeConstructor. When the YAML contains a scalar value with unquoted : , SnakeYAML throws a ScannerException, and the current implementation silently returns empty metadata (line 157–158):

try {
    loaded = createParserYaml().load(yamlContent);
} catch (RuntimeException e) {
    logger.debug("Failed to parse YAML frontmatter, returning empty metadata", e);
    return Map.of();  // ← All metadata lost, no user-friendly error
}

This is a common issue because:

Skill descriptions often contain error messages, log snippets, or key-value-like text that includes : .
Users writing SKILL.md files are not necessarily YAML experts and expect natural language to "just work".
The current behavior silently swallows the error, making it hard to debug.

I propose adding a pre-processing auto-repair mechanism in MarkdownSkillParser.parseYamlMetadata() that:

1. Attempts normal parsing first (no performance impact for valid YAML).
2. On failure, scans the YAML text for scalar values containing unquoted : patterns.
3. Wraps those values in double quotes and retries parsing.
4. Logs a WARN message when repair occurs, so users are aware their YAML is non-standard.

Proposed implementation outline:

private static Map<String, Object> parseYamlMetadata(String yamlContent) {
    try {
        return doParse(yamlContent);
    } catch (RuntimeException e) {
        String repaired = repairYamlWithUnquotedColons(yamlContent);
        if (!repaired.equals(yamlContent)) {
            logger.warn(
                "YAML frontmatter contained unquoted colons and was auto-repaired. "
                + "Consider quoting scalar values that contain ': ': {}",
                yamlContent.substring(0, Math.min(80, yamlContent.length())));
            return doParse(repaired);
        }
        logger.debug("Failed to parse YAML frontmatter, returning empty metadata", e);
        return Map.of();
    }
}

private static String repairYamlWithUnquotedColons(String yamlContent) {
    // For each "key: value" line:
    //   1. Check if value contains ": " not inside quotes
    //   2. If so, wrap the value in double quotes (escaping internal " and \)
    //   3. Return repaired YAML
}

Alternative solution: Custom SnakeYAML Constructor

public class LenientYamlConstructor extends SafeConstructor {
    // Override constructObject to catch ScannerException
    // and fall back to treating the node as a plain scalar
}

[hexly666]

Can assign this bug to me? thanks a lot.