Tencent/WeKnora · error

failed to parse YAML frontmatter: %w

Error message

failed to parse YAML frontmatter: %w

What it means

Parse wrapper in ParseSkillFile: UnmarshalSkillFrontmatter failed to decode the joined YAML frontmatter into the Skill, even after the repair pass. The YAML is malformed (bad indentation, unquoted colons, wrong types) or the repair heuristics could not normalize keys nested under `name`.

Source

Thrown at internal/agent/skills/skill.go:209

			frontmatterLines = append(frontmatterLines, line)
		} else if frontmatterEnded {
			bodyLines = append(bodyLines, line)
		}
	}

	if err := scanner.Err(); err != nil {
		return nil, fmt.Errorf("error reading SKILL.md: %w", err)
	}

	if !frontmatterEnded {
		return nil, errors.New("SKILL.md frontmatter is not properly closed with ---")
	}

	// Parse YAML frontmatter
	frontmatter := strings.Join(frontmatterLines, "\n")
	repaired, err := UnmarshalSkillFrontmatter(frontmatter, skill)
	if err != nil {
		return nil, fmt.Errorf("failed to parse YAML frontmatter: %w", err)
	}
	skill.FrontmatterRepaired = repaired
	if err := skill.applyInstallName(); err != nil {
		return nil, err
	}

	// Set body instructions
	skill.Instructions = strings.TrimSpace(strings.Join(bodyLines, "\n"))
	skill.Loaded = true

	// Validate
	if err := skill.Validate(); err != nil {
		return nil, fmt.Errorf("skill validation failed: %w", err)
	}

	return skill, nil
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Fix the YAML frontmatter: correct indentation, quote values containing colons
2. Ensure required keys (name, description) are top-level, not nested under `name:`
3. Inspect the wrapped YAML library error for the exact line/column

When it happens

Trigger: Thrown at internal/agent/skills/skill.go:209 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/dff63d2f0b9d6589. Report an issue: GitHub.