最近在调试一个自定义 Codex skill：`remote-shell-safe`。目录结构、`SKILL.md`、frontmatter 看起来都没问题：

---
name: remote-shell-safe
description: Use when running long or quoting-sensitive Windows PowerShell commands.
---
 

但奇怪的是，新开 session 后，这个 skill 一直没有出现在 `Available skills` 里。起初怀疑过几个方向：是不是 `metadata` 字段不兼容？是不是 `agents/openai.yaml` 有问题？是不是 skill 名称里的 hyphen `-` 不被支持？

后来验证发现，这些都不是根因。

真正的问题是：`SKILL.md` 文件开头多了 UTF-8 BOM。

也就是说，文件肉眼看起来是：

---
name: remote-shell-safe
 

但实际字节是：

EF BB BF 2D 2D 2D
 

其中 `EF BB BF` 是 UTF-8 BOM，`2D 2D 2D` 才是 `---`。Codex 的 skill loader 期望文件第一个字符就是 `-`，但它实际读到的是隐藏的 BOM，于是没有识别出 YAML frontmatter，最终整个 skill 被跳过。

用本地 validator 验证时，也能看到类似错误：

No YAML frontmatter found
 

移除 BOM 后，文件头变成：

2D 2D 2D
 

validator 通过：

Skill is valid!
 

重启 Codex Desktop 后，`remote-shell-safe` 正常出现在 session 的 skill 列表里。

这个问题的结论很简单：

- `remote-shell-safe` 这种 hyphen-case 命名是没问题的。
- `SKILL.md` 的 frontmatter 也没问题。
- 真正的问题是文件保存成了 **UTF-8 with BOM**。
- Codex skill 文件应保存为 **UTF-8 without BOM**。

以后如果遇到“skill 文件明明存在，但 session 看不到”的情况，可以优先检查：

1. `SKILL.md` 是否在 skill 目录根部。
2. frontmatter 是否从文件第一行开始。
3. 文件开头是否有 BOM。
4. 用 validator 检查是否能识别 YAML frontmatter。

这类 bug 很隐蔽，因为编辑器里看起来一切正常，但 loader 看到的是字节，不是我们的肉眼。