siyuan-note/siyuan · error

SKILL.md frontmatter missing 'name' field

Error message

SKILL.md frontmatter missing 'name' field

What it means

installFromSingleSkillMD installs a single SKILL.md payload passed directly (not inside a zip). It parses the YAML frontmatter and requires a non-empty 'name' field, since there is no directory name to fall back to. Without it, the skill cannot be identified or stored, so the error is thrown before any file is written.

Solutions

1. Add 'name: <skill-name>' to the YAML frontmatter at the top of the SKILL.md
2. Confirm the file starts with '---' delimiters so the frontmatter is parsed at all
3. Ensure the name passes validateSkillName (no spaces/invalid chars)

Example fix

// before
# My Skill
Some content...

// after
---
name: my-skill
description: Does something useful
---
# My Skill
Some content...

const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
const hasName = m && /^name:\s*\S+/.test(m[1]);
if (!hasName) throw new Error('SKILL.md frontmatter missing name');

try {
  await api.installSkill(mdBytes);
} catch (e) {
  if (e.message.includes("missing 'name' field")) {
    // prepend frontmatter with name before retry
  }
}

When it happens

Trigger: Passing SKILL.md content to InstallSkill (single-file install path) where the frontmatter lacks 'name' or it is empty; file has no frontmatter block at all.

Common situations: Copying a skill body from documentation without its frontmatter; hand-written SKILL.md missing the metadata block; a tool that strips frontmatter during export.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• no valid skill installed
• newPath is required
• 346
• 348
• 349

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/1eb7789b3836611d. Report an issue: GitHub.

Appendix: source

Thrown at kernel/util/skill.go:857

		desc := fm["description"]
		if desc == "" {
			desc = firstLine(body)
		}
		result.Descriptions = append(result.Descriptions, desc)
	}
	if len(result.Names) == 0 {
		return nil, errors.New("no valid skill installed")
	}
	return result, nil
}

// installFromSingleSkillMD 把单个 SKILL.md 文本内容落地为一个 skill
func installFromSingleSkillMD(data []byte) (*InstallSkillResult, error) {
	content := string(data)
	fm, body := parseSkillFrontmatter(content)
	name := fm["name"]
	if name == "" {
		return nil, errors.New("SKILL.md frontmatter missing 'name' field")
	}
	if err := validateSkillName(name); err != nil {
		return nil, err
	}
	if err := SaveSkill(name, content); err != nil {
		return nil, err
	}
	return &InstallSkillResult{
		Names:        []string{name},
		Descriptions: []string{firstLine(body)},
	}, nil
}

View on GitHub (pinned to 9f775e8a12)