Skills on KnightLi的博客

Codex Skill 明明在目錄裡，為什麼就是不顯示？

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

這次遇到的問題很隱蔽：~/.codex/skills 裡明明已經放好了多個 skill，新開 Codex 執行緒之後，側邊欄卻還是只能看到少數幾個。

一開始看起來像是快取或索引問題，但實際原因更具體：幾個 SKILL.md 文件開頭帶了 UTF-8 BOM，Codex 0.111.0 的 skill loader 沒有跳過這個位元組，於是誤判文件沒有合法的 YAML front matter。

現象

本地目錄裡有這些 skill：

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

但新開執行緒時，實際暴露出來的只有：

1
2

bilibili-speech-transcriber
product-cutout-normalize

也就是說，文件存在不等於當前會話一定能載入成功。Codex 會先解析每個 SKILL.md 的 front matter，解析失敗的 skill 會直接被排除。

排查

用 codex exec 啟動一個新會話時，可以看到更直接的錯誤。在 VS Code 等 IDE 中，可能看不到這些 log：

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

這些文件肉眼看起來都有正常的開頭：

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

真正的問題在位元組層面。

失敗文件的開頭是：

`1`	`EF-BB-BF-2D-2D-2D`

能正常載入的文件開頭是：

`1`	`2D-2D-2D`

2D-2D-2D 就是 ---。前面的 EF-BB-BF 是 UTF-8 BOM。

原因

Codex 0.111.0 的 skill loader 目前要求 SKILL.md 文件第一個位元組就是 --- 的第一個 -。

如果文件前面帶了 UTF-8 BOM，那麼文件實際開頭就不再是 ---，而是：

`1`	`BOM + ---`

於是 loader 會認為它沒有以前置資料分隔符開頭，最後報：

`1`	`missing YAML frontmatter delimited by ---`

這不是 skill 內容寫錯了，也不是目錄放錯了，而是編碼細節讓解析器沒認出來。

修復

把出問題的 SKILL.md 轉成無 BOM 的 UTF-8 即可。

PowerShell 可以這樣處理：

$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)
}

處理後再檢查文件頭，應該從：

`1`	`EF-BB-BF-2D-2D-2D`

變成：

`1`	`2D-2D-2D`

驗證

重新啟動一個 Codex 會話後，可見 skill 恢復為：

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

如果側邊欄仍然只顯示舊的列表，可以退出當前 Codex sidebar 或窗口，再重新打開專案。skill 列表通常在會話啟動時載入，中途改文件不一定會立刻刷新到當前執行緒。

最後一句

這類問題最容易誤判成「Codex 沒重新索引」或「skill 沒安裝好」。

實際排查時可以先看三件事：

SKILL.md 是否真的在正確目錄
文件頭部是否有合法的 --- front matter
文件是否是無 BOM 的 UTF-8

這次的關鍵就是第三點：文件看起來沒問題，但第一個位元組不是 -，Codex 就沒有把它當作一個有效 skill。

Codex 裡的 ~/.codex/skills 和專案/.codex/skills 有什麼差別

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

很多人整理 Codex skills 時，最容易卡住的問題就兩個：

~/.codex/skills 和 專案/.codex/skills 有什麼差別
為什麼 skill 明明在目錄裡，當前會話裡卻不一定顯示

這篇就直接說結論。

兩者的差別

先記最短版本：

~/.codex/skills 是你的全域技能庫
專案/.codex/skills 是這個倉庫的本地技能庫

`~/.codex/skills`

適合放：

你自己跨專案反覆會用的 skill
跟具體倉庫無關的通用流程
很明顯屬於你個人習慣的工作流

比如：

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

這類 skill 的特點就是：離開當前專案也還能用。

`專案/.codex/skills`

適合放：

只對這個倉庫成立的流程
跟當前專案目錄結構、腳本、模板綁定很深的規則
需要讓團隊一起共享的 skill

比如：

這個倉庫特有的發布流程
只能在這個專案裡用的生成模板
跟專案私有腳本強綁定的自動化步驟

這類 skill 的特點是：離開這個倉庫就沒意義。

什麼時候放全域，什麼時候放專案裡

直接這樣判斷就夠了：

跟你個人習慣有關，放 ~/.codex/skills
跟倉庫規則有關，放 專案/.codex/skills
能跨專案複用，優先放全域
要多人共享、跟倉庫一起演進，優先放專案裡

當前這個倉庫是什麼情況

按我現在看到的實際狀態：

你的本機裡有 ~/.codex/skills
當前倉庫裡沒有 .codex/skills

所以你現在主要依賴的是全域 skills。

也就是說，像 post-rewrite、post-translate、git-commit-push 這些流程，現在更多是你個人工作流的一部分，不是這個倉庫顯式自帶的一部分。

為什麼磁碟裡有，當前會話裡卻不一定顯示

這裡要分清兩件事：

磁碟存在：說明 skill 文件在本地目錄裡
會話暴露：說明當前會話把它註冊進了可用 skill 列表

這兩者不是一回事。

所以會出現這種情況：

~/.codex/skills 裡已經有 skill
但 / 後面的列表裡沒有顯示

這通常不代表 skill 壞了，更常見的原因是：當前會話沒有把它重新索引進去。

怎樣讓 skill 被當前會話暴露

最實用的步驟就這幾條：

1. 目錄放對

全域：

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

專案級：

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

2. `SKILL.md` 頭部可識別

最少要有：

---
name: your-skill-name
description: 這個 skill 是做什麼的
---

3. 新建或修改後，開新會話

很多時候 skill 沒顯示，不是文件有問題，而是當前會話啟動時就已經把可用 skill 列表定下來了。

所以你中途新建 skill，磁碟裡雖然已經有了，這次會話也未必會重新認。

最穩的做法就是：

放好 skill
結束當前會話
重新進入專案
開一個新會話
再看 / 裡有沒有出現

4. 專案 skill 最好提前放好

如果你想讓 專案/.codex/skills 更穩定地被識別，最好在進入倉庫、啟動會話之前，就把這些 skill 放進專案裡。

最後一句

最短結論就是：

~/.codex/skills 是你的個人技能庫
專案/.codex/skills 是倉庫的本地規則庫
skill 在目錄裡，不等於當前會話一定會顯示
想讓它顯示，最常見的辦法就是放對目錄、寫好 SKILL.md，然後開新會話

Skills on KnightLi的博客

Codex Skill 明明在目錄裡，為什麼就是不顯示？

現象

排查

原因

修復

驗證

最後一句

Codex 裡的 ~/.codex/skills 和 專案/.codex/skills 有什麼差別

兩者的差別

~/.codex/skills

專案/.codex/skills

什麼時候放全域，什麼時候放專案裡

當前這個倉庫是什麼情況

為什麼磁碟裡有，當前會話裡卻不一定顯示

怎樣讓 skill 被當前會話暴露

1. 目錄放對

2. SKILL.md 頭部可識別

3. 新建或修改後，開新會話

4. 專案 skill 最好提前放好

最後一句

Codex 裡的 ~/.codex/skills 和專案/.codex/skills 有什麼差別

`~/.codex/skills`

`專案/.codex/skills`

2. `SKILL.md` 頭部可識別