feat(skill): add YAML auto-repair for unquoted colons in frontmatter

Enhance MarkdownSkillParser to automatically repair YAML frontmatter
containing unquoted colon-space patterns in scalar values. When SnakeYAML
fails to parse, the parser now attempts to quote problematic values
before giving up.

Refs #1442

Author: hexly666

agentscope-core/src/main/java/io/agentscope/core/skill/util/MarkdownSkillParser.java

@@ -154,8 +154,22 @@ private static Map<String, Object> parseYamlMetadata(String yamlContent) {
         try {
             loaded = createParserYaml().load(yamlContent);
         } catch (RuntimeException e) {
-            logger.debug("Failed to parse YAML frontmatter, returning empty metadata", e);
-            return Map.of();
+            String repaired = repairYamlWithUnquotedColons(yamlContent);
+            if (!repaired.equals(yamlContent)) {
+                try {
+                    loaded = createParserYaml().load(repaired);
+                    logger.warn(
+                            "YAML frontmatter contained unquoted colons and was auto-repaired. "
+                                    + "Consider quoting scalar values containing ': ': {}",
+                            yamlContent.substring(0, Math.min(80, yamlContent.length())));
+                } catch (RuntimeException e2) {
+                    logger.debug("Failed to repair YAML frontmatter, returning empty metadata", e2);
+                    return Map.of();
+                }
+            } else {
+                logger.debug("Failed to parse YAML frontmatter, returning empty metadata", e);
+                return Map.of();
+            }
         }
 
         if (loaded == null) {
@@ -182,6 +196,99 @@ private static Map<String, Object> parseYamlMetadata(String yamlContent) {
         return metadata;
     }
 
+    /**
+     * Attempts to repair YAML content that contains unquoted colons in scalar values.
+     *
+     * <p>This handles the common case where a value contains patterns like "key:" that YAML
+     * interprets as mapping keys, for example:
+     * <pre>
+     * description: test, node: cannot find EDI partner
+     * </pre>
+     *
+     * <p>The repair strategy wraps values in double quotes when they contain ": " patterns
+     * that would otherwise be parsed as key-value separators.
+     *
+     * @param yamlContent The original YAML content that failed to parse
+     * @return Repaired YAML content, or the original if no repair was possible
+     */
+    private static String repairYamlWithUnquotedColons(String yamlContent) {
+        StringBuilder result = new StringBuilder();
+        String[] lines = yamlContent.split("\n", -1);
+
+        for (String line : lines) {
+            int firstColon = line.indexOf(':');
+            if (firstColon > 0 && line.length() > firstColon + 1) {
+                String keyPart = line.substring(0, firstColon);
+                String valuePart = line.substring(firstColon + 1);
+
+                String trimmedKey = keyPart.trim();
+                if (!trimmedKey.isEmpty() && !trimmedKey.contains(" ")) {
+                    if (needsQuoting(valuePart)) {
+                        String repairedValue = quoteValue(valuePart);
+                        line = keyPart + ":" + repairedValue;
+                    }
+                }
+            }
+            result.append(line).append('\n');
+        }
+
+        if (result.length() > 0) {
+            result.setLength(result.length() - 1);
+        }
+        return result.toString();
+    }
+
+    /**
+     * Checks if a YAML value needs quoting because it contains unquoted colon-space patterns.
+     */
+    private static boolean needsQuoting(String value) {
+        String trimmed = value.trim();
+        if (trimmed.isEmpty()) {
+            return false;
+        }
+
+        if ((trimmed.startsWith("\"") && trimmed.endsWith("\""))
+                || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            return false;
+        }
+
+        return findUnquotedColonSpace(trimmed) >= 0;
+    }
+
+    /**
+     * Finds the index of ": " that is not inside quotes.
+     *
+     * @return Index of the unquoted ": " or -1 if none found
+     */
+    private static int findUnquotedColonSpace(String value) {
+        boolean inDoubleQuotes = false;
+        boolean inSingleQuotes = false;
+
+        for (int i = 0; i < value.length() - 1; i++) {
+            char c = value.charAt(i);
+            if (c == '"' && !inSingleQuotes) {
+                inDoubleQuotes = !inDoubleQuotes;
+            } else if (c == '\'' && !inDoubleQuotes) {
+                inSingleQuotes = !inSingleQuotes;
+            } else if (!inDoubleQuotes
+                    && !inSingleQuotes
+                    && c == ':'
+                    && value.charAt(i + 1) == ' ') {
+                return i;
+            }
+        }
+        return -1;
+    }
+
+    /**
+     * Quotes a YAML value in double quotes, escaping any internal double quotes and backslashes.
+     */
+    private static String quoteValue(String value) {
+        String trimmed = value.trim();
+        String escaped = trimmed.replace("\\", "\\\\").replace("\"", "\\\"");
+        return " \"" + escaped + "\"";
+    }
+
     private static LoaderOptions createLoaderOptions() {
         LoaderOptions options = new LoaderOptions();
         options.setAllowDuplicateKeys(false);

agentscope-core/src/test/java/io/agentscope/core/skill/util/MarkdownSkillParserTest.java

@@ -730,4 +730,133 @@ void testMetadataImmutable() {
                     () -> parsed.getMetadata().put("description", "desc"));
         }
     }
+
+    @Nested
+    @DisplayName("YAML Auto-Repair Tests")
+    class YamlAutoRepairTests {
+
+        @Test
+        @DisplayName("Should auto-repair description with unquoted colons")
+        void testAutoRepairUnquotedColons() {
+            String markdown =
+                    "---\n"
+                            + "name: testskils\n"
+                            + "description: 测试skills, node: 无法找到EDI Partner、EDI Partner不存在\n"
+                            + "---\n"
+                            + "# Skill Content";
+
+            ParsedMarkdown parsed = MarkdownSkillParser.parse(markdown);
+
+            assertNotNull(parsed);
+            assertTrue(parsed.hasFrontmatter());
+            assertEquals("testskils", parsed.getMetadata().get("name"));
+            String description = (String) parsed.getMetadata().get("description");
+            assertNotNull(description);
+            assertTrue(description.contains("node:"));
+            assertTrue(description.contains("无法找到EDI Partner"));
+        }
+
+        @Test
+        @DisplayName("Should auto-repair description with error message containing colon")
+        void testAutoRepairErrorMessageWithColon() {
+            String markdown =
+                    "---\n"
+                        + "name: edi-skill\n"
+                        + "description: When error contains: Can't find the EDI Customer setup\n"
+                        + "---\n"
+                        + "# Content";
+
+            ParsedMarkdown parsed = MarkdownSkillParser.parse(markdown);
+
+            assertTrue(parsed.hasFrontmatter());
+            String description = (String) parsed.getMetadata().get("description");
+            assertNotNull(description);
+            assertTrue(description.contains("Can't find the EDI Customer setup"));
+        }
+
+        @Test
+        @DisplayName("Should handle already quoted values without double-quoting")
+        void testAlreadyQuotedValuesNotDoubleQuoted() {
+            String markdown =
+                    "---\n"
+                            + "name: test\n"
+                            + "description: \"Already quoted: with colon\"\n"
+                            + "---\n"
+                            + "# Content";
+
+            ParsedMarkdown parsed = MarkdownSkillParser.parse(markdown);
+
+            assertTrue(parsed.hasFrontmatter());
+            assertEquals("Already quoted: with colon", parsed.getMetadata().get("description"));
+        }
+
+        @Test
+        @DisplayName("Should handle multiple fields with unquoted colons")
+        void testMultipleFieldsWithUnquotedColons() {
+            String markdown =
+                    "---\n"
+                            + "name: multi-colon\n"
+                            + "description: Error: something failed, detail: node: not found\n"
+                            + "example: status: error, code: 500\n"
+                            + "---\n"
+                            + "# Content";
+
+            ParsedMarkdown parsed = MarkdownSkillParser.parse(markdown);
+
+            assertTrue(parsed.hasFrontmatter());
+            String description = (String) parsed.getMetadata().get("description");
+            assertNotNull(description);
+            assertTrue(description.contains("Error:"));
+            assertTrue(description.contains("detail:"));
+            String example = (String) parsed.getMetadata().get("example");
+            assertNotNull(example);
+            assertTrue(example.contains("status:"));
+            assertTrue(example.contains("code:"));
+        }
+
+        @Test
+        @DisplayName("Should still parse valid YAML without repair")
+        void testValidYamlNoRepairNeeded() {
+            String markdown =
+                    "---\n"
+                            + "name: valid-yaml\n"
+                            + "description: A normal description without colons\n"
+                            + "version: 1.0.0\n"
+                            + "---\n"
+                            + "# Content";
+
+            ParsedMarkdown parsed = MarkdownSkillParser.parse(markdown);
+
+            assertTrue(parsed.hasFrontmatter());
+            assertEquals("valid-yaml", parsed.getMetadata().get("name"));
+            assertEquals(
+                    "A normal description without colons", parsed.getMetadata().get("description"));
+            assertEquals("1.0.0", parsed.getMetadata().get("version"));
+        }
+
+        @Test
+        @DisplayName("Should handle Chinese text with colons")
+        void testChineseTextWithColons() {
+            String markdown =
+                    "---\n"
+                        + "name: chinese-skill\n"
+                        + "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。\n"
+                        + "---\n"
+                        + "# Content";
+
+            ParsedMarkdown parsed = MarkdownSkillParser.parse(markdown);
+
+            assertTrue(parsed.hasFrontmatter());
+            assertEquals("chinese-skill", parsed.getMetadata().get("name"));
+            String description = (String) parsed.getMetadata().get("description");
+            assertNotNull(description);
+            assertTrue(description.contains("无法找到EDI Partner"));
+            assertTrue(description.contains("850订单"));
+            assertTrue(description.contains("EDI Customer setup"));
+        }
+    }
 }