siyuan-note/siyuan · error

install skill %s failed: %s

Error message

install skill %s failed: %s

What it means

Thrown by installSkillDirs when filelock.Copy fails while copying a discovered skill directory from the temp unzip area into SkillsDir(). Earlier steps (reading SKILL.md, validating the name, removing any pre-existing dest) have already succeeded.

Source

Thrown at kernel/util/skill.go:532

				continue
			}
			name = filepath.Base(rel)
		}
		if verr := validateSkillName(name); verr != nil {
			logging.LogWarnf("skip invalid skill name [%s]: %s", name, verr)
			continue
		}

		destDir := filepath.Join(SkillsDir(), name)
		if err := os.MkdirAll(SkillsDir(), 0755); err != nil {
			return nil, err
		}
		// 覆盖式安装：先清旧目录
		if gulu.File.IsExist(destDir) {
			os.RemoveAll(destDir)
		}
		if err := filelock.Copy(srcDir, destDir); err != nil {
			return nil, fmt.Errorf("install skill %s failed: %s", name, err)
		}
		result.Names = append(result.Names, name)
		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)

View on GitHub (pinned to 251596fc0d)

Solutions

1. Verify write permissions and free space under the workspace data/storage/ai/agent/skills directory.
2. Retry after disabling any sync client (OneDrive/Dropbox) or AV that may lock the directory on Windows.
3. Inspect the skill archive for special files or symlinks and remove them.
4. Re-run install after freeing disk space.

res, err := util.InstallSkill(src)
if err != nil && strings.HasPrefix(err.Error(), "install skill ") {
    // inspect destination permissions and free space, then retry once
    ensureWritable(util.SkillsDir())
}

When it happens

Trigger: A permission error writing into SkillsDir(); a path-length or filename encoding issue on the destination filesystem; the source directory contains a file filelock cannot copy (special files, symlinks it rejects); disk full.

Common situations: Restrictive filesystem permissions on data/storage/ai/agent/skills; antivirus or sync software locking files on Windows; an exotic file in the skill archive; insufficient disk space.

Related errors

• write data [%s] failed: %s
• read image failed: %w
• save generated image failed: %w
• failed to persist key backup: %w
• enable encrypted notebook failed: failed to persist key back

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