siyuan-note/siyuan · warning

only UTF-8 text files can be edited

Error message

only UTF-8 text files can be edited

What it means

ErrSkillEncoding indicates the file content is not valid UTF-8 text: either it starts with a UTF-16/UTF-32 BOM (\xff\xfe, \xfe\xff, \x00\x00\xfe\xff) or utf8.ValidString fails. The skill editor only supports UTF-8 text, so such files are rejected on read and write instead of being silently mangled.

Solutions

1. Re-save the file as UTF-8 (without UTF-16/UTF-32 BOM) using the editor's encoding option
2. Convert in place: iconv -f UTF-16 -t UTF-8 file.md > out.md, then replace the original
3. In PowerShell use utf8 encoding: Out-File -Encoding utf8

Example fix

// before (PowerShell 5)
Get-Content a.md | Out-File SKILL.md   # UTF-16LE

// after
Get-Content a.md | Out-File SKILL.md -Encoding utf8

function isUtf8WithoutBOM(bytes) {
  if (bytes[0] === 0xff && bytes[1] === 0xfe) return false;
  if (bytes[0] === 0xfe && bytes[1] === 0xff) return false;
  try { new TextDecoder('utf-8', {fatal: true}).decode(bytes); return true; }
  catch { return false; }
}

try {
  await api.manageSkillFiles({action: 'write', path, content});
} catch (e) {
  if (e.message.includes('only UTF-8')) {
    // convert file encoding to UTF-8 before retry
  }
}

When it happens

Trigger: Reading/writing a skill file saved as UTF-16 (with BOM) or containing invalid UTF-8 byte sequences; validateManagedSkillSource rejects it in ManageSkillFiles.

Common situations: Editing SKILL.md on Windows with a UTF-16-capable editor; PowerShell 5's Out-File defaulting to UTF-16LE; copying content from a binary/legacy-encoded source.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• 344
• binary files cannot be edited as text
• invalid template source
• skill resource is not valid UTF-8
• template source is not UTF-8

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

Appendix: source

Thrown at kernel/util/skill_manage.go:31

	"os"
	"path"
	"path/filepath"
	"strings"
	"sync"
	"unicode"
	"unicode/utf8"

	"github.com/88250/lute/ast"
	"github.com/siyuan-note/filelock"
)

const maxManagedSkillSourceSize = 8 * 1024 * 1024

var skillManagementLock sync.Mutex

var (
	ErrSkillBinary   = errors.New("binary files cannot be edited as text")
	ErrSkillEncoding = errors.New("only UTF-8 text files can be edited")
	ErrSkillTooLarge = errors.New("text files must be at most 8 MiB")
)

type SkillFileRequest struct {
	Action   string
	Path     string
	Target   string
	Content  string
	Revision string
}

type SkillFileEntry struct {
	Path     string
	IsDir    bool
	Editable bool
}

type SkillFileData struct {

View on GitHub (pinned to 9f775e8a12)