siyuan-note/siyuan · error

SKILL.md frontmatter missing 'name' field

Error message

SKILL.md frontmatter missing 'name' field

What it means

Thrown by installFromSingleSkillMD when a text/plain SKILL.md payload's parsed frontmatter contains no 'name' key. Unlike the zip path, the single-file installer has no directory name to fall back on, so the name field is mandatory.

Source

Thrown at kernel/util/skill.go:553

		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 251596fc0d)

Solutions

1. Add 'name: my-skill' to the SKILL.md frontmatter between the '---' delimiters.
2. Ensure the frontmatter block is well-formed: opening '---', 'name: value' lines, closing '---'.
3. Confirm the URL serves the raw markdown, not a rendered HTML page (use raw.githubusercontent.com).

Example fix

// before
---
description: does a thing
---
# My Skill
...

// after
---
name: my-skill
description: does a thing
---
# My Skill
...

// verify the raw SKILL.md declares a name before installing
resp, _ := http.Get(rawSkillMDURL)
b, _ := io.ReadAll(resp.Body)
fm, _ := parseFrontmatter(string(b))
if fm["name"] == "" {
    return errors.New("SKILL.md must declare a 'name' frontmatter field")
}

When it happens

Trigger: Installing a raw SKILL.md URL whose frontmatter omits 'name'; the frontmatter is malformed (missing '---' delimiters, bad key:value syntax); the file has no frontmatter at all.

Common situations: Author forgot the name field; frontmatter uses a different delimiter or indentation the parser does not recognize; the URL actually returns an HTML wrapper page that happens to start with '---'.

Related errors

• no SKILL.md found in the archive
• no valid skill installed
• marketplace package manifest not found or invalid
• marketplace package name mismatch: expected [%s], got [%s]
• multiple marketplace package manifests found

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/1eb7789b3836611d. Report an issue: GitHub.