Tencent/WeKnora · error

skill validation failed: %w

Error message

skill validation failed: %w

What it means

Validation wrapper in ParseSkillFile: the YAML parsed successfully but Skill.Validate rejected the skill (empty/reserved/oversized name, bad name characters, XML tags in name, empty or oversized description, etc.). The SKILL.md structure is fine; its metadata violates the skill specification.

Source

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

	// 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
}

// ParseSkillMetadata parses only the metadata from a SKILL.md file content
// This is a lightweight operation for skill discovery (Level 1 only)
func ParseSkillMetadata(content string) (*SkillMetadata, error) {
	skill, err := ParseSkillFile(content)
	if err != nil {
		return nil, err
	}
	return skill.ToMetadata(), nil
}

// IsOnDemandInstallerPath reports whether path is a first-use dependency
// installer (scripts/install_deps.py and friends). Skills ship these to defer
// optional packages to chat time, which cannot work once the skill tree is

View on GitHub (pinned to 988cbb0330)

Solutions

1. Read the wrapped Validate error to see which rule failed
2. Fix the offending frontmatter field (name characters, reserved words, description length)
3. Re-run ParseSkillFile to confirm the skill now validates

When it happens

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

Common situations: See trigger scenarios.

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