Skills on KnightLi Blog

Why Does a Codex Skill Exist in the Directory but Still Not Show Up?

Wed, 29 Apr 2026 11:18:00 +0800

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:

~/.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:

---
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:

$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:

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.

What Is the Difference Between ~/.codex/skills and Project .codex/skills in Codex

Wed, 29 Apr 2026 11:08:00 +0800

When organizing Codex skills, people most often get stuck on two questions:

What is the difference between ~/.codex/skills and project/.codex/skills?
Why does a skill exist in the directory but not appear in the current session?

Here is the short version.

The Difference

The simplest way to remember it:

~/.codex/skills is your global skill library
project/.codex/skills is the local skill library for that repository

`~/.codex/skills`

Use it for:

skills you personally reuse across projects
general workflows that are not tied to a specific repository
workflows that clearly belong to your own habits

For example:

post-rewrite
post-translate
git-commit-push
hugo-rsync-deploy
bilibili-speech-transcriber

The key trait of this kind of skill is: it still makes sense outside the current project.

`project/.codex/skills`

Use it for:

workflows that only apply to this repository
rules tightly coupled to the current project structure, scripts, or templates
skills that should be shared by the team

For example:

a publishing workflow specific to this repository
a generation template that only works in this project
automation steps tightly bound to private project scripts

The key trait of this kind of skill is: it stops being meaningful once it leaves this repository.

When to Use Global and When to Use Project Skills

This rule of thumb is enough:

If it is about your personal habits, put it in ~/.codex/skills
If it is about repository rules, put it in project/.codex/skills
If it can be reused across projects, prefer global
If it should be shared by multiple people and evolve with the repository, prefer project-level

The Current Repository

Based on the current state:

your machine has ~/.codex/skills
this repository does not have .codex/skills

So right now, you mainly rely on global skills.

That means workflows such as post-rewrite, post-translate, and git-commit-push are currently more like part of your personal workflow, not something explicitly bundled with this repository.

Why a Skill Exists on Disk but May Not Appear in the Current Session

There are two different things here:

Existing on disk: the skill file exists in a local directory
Exposed to the session: the current session registered it into the available skill list

These are not the same thing.

So this can happen:

a skill already exists under ~/.codex/skills
but it does not appear in the list after /

This usually does not mean the skill is broken. More often, it means: the current session has not re-indexed it.

How to Make a Skill Available in the Current Session

The practical checklist is short.

1. Put It in the Right Directory

Global:

`1`	`~/.codex/skills/<skill-name>/SKILL.md`

Project-level:

`1`	`project/.codex/skills/<skill-name>/SKILL.md`

2. Make the `SKILL.md` Header Recognizable

At minimum, it needs:

---
name: your-skill-name
description: What this skill does
---

3. Open a New Session After Creating or Editing It

In many cases, a skill does not appear because the current session already fixed its available skill list when it started.

So if you create a skill in the middle of a session, it may already exist on disk, but this session may not recognize it.

The most reliable workflow is:

Put the skill in place
End the current session
Re-enter the project
Open a new session
Check whether it appears under /

4. Put Project Skills in Place Before Starting

If you want project/.codex/skills to be recognized more reliably, put those skills into the project before entering the repository and starting the session.

One Last Line

The shortest conclusion is:

~/.codex/skills is your personal skill library
project/.codex/skills is the repository’s local rule library
a skill existing in the directory does not mean the current session will always show it
the most common fix is to put it in the right directory, write a valid SKILL.md, and then start a new session

Skills on KnightLi Blog

Why Does a Codex Skill Exist in the Directory but Still Not Show Up?

Symptom

Investigation

Cause

Fix

Verification

One Last Line

What Is the Difference Between ~/.codex/skills and Project .codex/skills in Codex

The Difference

~/.codex/skills

project/.codex/skills

When to Use Global and When to Use Project Skills

The Current Repository

Why a Skill Exists on Disk but May Not Appear in the Current Session

How to Make a Skill Available in the Current Session

1. Put It in the Right Directory

2. Make the SKILL.md Header Recognizable

3. Open a New Session After Creating or Editing It

4. Put Project Skills in Place Before Starting

One Last Line

`~/.codex/skills`

`project/.codex/skills`

2. Make the `SKILL.md` Header Recognizable