This problem was easy to miss: several skills were already placed under ~/.codex/skills, but after opening a new Codex thread, the sidebar still showed only a small subset of them.

At first, it looked like a cache or indexing issue. The real cause was more specific: several SKILL.md files started with a UTF-8 BOM. Codex 0.111.0’s skill loader did not skip that byte sequence, so it misjudged the files as having no valid YAML front matter.

Symptom

The local directory contained these skills:

1
2
3
4

~/.codex/skills/git-commit-push/SKILL.md
~/.codex/skills/hugo-rsync-deploy/SKILL.md
~/.codex/skills/bilibili-speech-transcriber/SKILL.md
~/.codex/skills/product-cutout-normalize/SKILL.md

But after opening a new thread, the actually exposed skills were only:

1
2

bilibili-speech-transcriber
product-cutout-normalize

In other words, a file existing on disk does not mean the current session can load it successfully. Codex parses the front matter of each SKILL.md first. If parsing fails, that skill is excluded directly.

Investigation

Starting a fresh session with codex exec showed a more direct error. In VS Code or other IDEs, these logs may not be visible:

1
2

failed to load skill C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md: missing YAML frontmatter delimited by ---
failed to load skill C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md: missing YAML frontmatter delimited by ---

Visually, these files seemed to have a normal header:

1
2
3
4

---
name: post-rewrite
description: ...
---

The real problem was at the byte level.

The beginning of a failing file was:

1

EF-BB-BF-2D-2D-2D

The beginning of a file that loaded correctly was:

1

2D-2D-2D

2D-2D-2D is ---. The preceding EF-BB-BF is the UTF-8 BOM.

Cause

In Codex 0.111.0, the skill loader expects the first byte of SKILL.md to be the first - in ---.

If the file starts with a UTF-8 BOM, the actual beginning becomes:

1

BOM + ---

So the loader thinks the file does not start with the front matter delimiter and reports:

1

missing YAML frontmatter delimited by ---

The skill content was not wrong, and the directory was not wrong either. A small encoding detail prevented the parser from recognizing the file.

Fix

Convert the affected SKILL.md files to UTF-8 without BOM.

In PowerShell, this can be done like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$paths = @(
  'C:\Users\knightli\.codex\skills\git-commit-push\SKILL.md',
  'C:\Users\knightli\.codex\skills\hugo-rsync-deploy\SKILL.md',
)

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)

foreach ($p in $paths) {
  $text = [IO.File]::ReadAllText($p, [Text.Encoding]::UTF8)
  [IO.File]::WriteAllText($p, $text, $utf8NoBom)
}

After processing, the file header should change from:

1

EF-BB-BF-2D-2D-2D

to:

1

2D-2D-2D

Verification

After restarting a Codex session, the visible skills were restored to:

1
2
3
4

git-commit-push-zh
hugo-rsync-deploy
bilibili-speech-transcriber
product-cutout-normalize

If the sidebar still shows the old list, close the current Codex sidebar or window and reopen the project. The skill list is usually loaded when the session starts, so changes made in the middle of a session may not refresh immediately.

One Last Line

This kind of issue is easy to mistake for “Codex did not re-index” or “the skill was not installed correctly.”

When troubleshooting, check these three things first:

• whether SKILL.md is really in the correct directory
• whether the file has valid --- front matter at the top
• whether the file is UTF-8 without BOM

The key in this case was the third point: the file looked fine, but its first byte was not -, so Codex did not treat it as a valid skill.