Skill Creator scripts fail to read UTF-8 SKILL.md files on Windows non-UTF-8 locales

Open 💬 1 comment Opened Jul 14, 2026 by WilliamClifton-dev

What issue are you seeing?

The bundled Skill Creator scripts rely on the platform default text encoding when reading or writing UTF-8 skill files. On Windows systems using a non-UTF-8 locale, quick_validate.py can fail with UnicodeDecodeError when a valid UTF-8 SKILL.md contains characters such as smart quotes, an em dash, or CJK text.

Observed error:

Traceback (most recent call last):
  File ".../skill-creator/scripts/quick_validate.py", line 99, in <module>
    valid, message = validate_skill(sys.argv[1])
  File ".../skill-creator/scripts/quick_validate.py", line 23, in validate_skill
    content = skill_md.read_text()
  File ".../pathlib.py", line 1028, in read_text
    return f.read()
UnicodeDecodeError: 'gbk' codec can't decode byte 0x9d in position 2788: illegal multibyte sequence

The current implementation uses:

content = skill_md.read_text()

generate_openai_yaml.py has the same implicit-encoding read and also calls write_text() without an encoding, so it appears susceptible to the same locale-dependent behavior.

What steps can reproduce the bug?

Environment used:

OS: Windows NT 10.0.26200.0
System culture: zh-CN
Python: 3.13.9
locale.getencoding(): cp936
Codex CLI: 0.139.0
PyYAML: 6.0.3
  1. Create a valid skill whose SKILL.md is encoded as UTF-8 and contains a character not decodable under CP936/GBK, for example:

```markdown
---
name: utf8-validation-test
description: Validate a skill containing UTF-8 punctuation.
---

# UTF-8 validation test

Do not ask “should I continue?” during uninterrupted execution.
```

  1. On a Chinese Windows locale, run the bundled validator normally:

``powershell
python path\to\skill-creator\scripts\quick_validate.py path\to\utf8-validation-test
``

  1. Observe UnicodeDecodeError from skill_md.read_text().
  1. Run the same command with Python UTF-8 mode enabled:

``powershell
python -X utf8 path\to\skill-creator\scripts\quick_validate.py path\to\utf8-validation-test
``

The skill validates successfully.

What is the expected behavior?

Skill Creator scripts should read and write skill files consistently as UTF-8 on every supported platform, independent of the user's Windows locale.

A narrow fix would be to specify UTF-8 explicitly:

content = skill_md.read_text(encoding="utf-8")

and:

output_path.write_text(content, encoding="utf-8")

A regression test containing non-ASCII UTF-8 text would prevent the platform default encoding from being reintroduced.

Additional information

Current affected sources:

  • codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py
  • codex-rs/skills/src/assets/samples/skill-creator/scripts/generate_openai_yaml.py

I searched open issues for quick_validate, skill creator encoding, GBK, and UnicodeDecodeError and did not find an issue covering this behavior. Issue #25548 also concerns quick_validate.py, but it addresses frontmatter guidance rather than file encoding.

I can prepare the small fix and regression coverage if a maintainer would like to invite a pull request under the repository's external contribution policy.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗