Codex Skills 放在哪裡：使用者級、倉庫級與載入失敗排查

Codex Skills 的官方共享目錄已統一為 .agents/skills。舊說明把 ~/.codex/skills 與 專案/.codex/skills 當成標準路徑，會讓新 Skill 放錯位置，也混淆個人設定目錄和可共享技能。

最短結論：個人跨專案重複使用的 Skill 放在 $HOME/.agents/skills；倉庫規則放在倉庫內的 .agents/skills。每個 Skill 都要有自己的目錄和 SKILL.md。

四種載入作用域

Codex 會從目前工作目錄向上掃描到倉庫根目錄，因此 monorepo 可以在子目錄放更具體的 .agents/skills。倉庫級 Skill 可隨 Git 審查與版本管理；使用者級 Skill 不應承載只對單一專案成立的假設。

舊版本、插件或本地 runtime 仍可能出現 .codex/skills，但不應再作為新建共享 Skill 的預設路徑。判斷時以目前官方文件和本次會話列出的 Skills 為準。

最小可載入 Skill

1
2
3
4

.agents/
└── skills/
    └── verify-build/
        └── SKILL.md

SKILL.md 必須從合法 YAML front matter 開始：

1
2
3
4
5
6
7
8

---
name: verify-build
description: Run the repository build and report reproducible failures.
---

# Verify build

Run the documented build command, preserve logs, and do not publish artifacts.

name 應穩定且容易辨識；description 要說明何時適用，正文再定義步驟、邊界與驗收。

檔案存在卻沒有載入

1. 檢查實際路徑

確認沒有多套一層目錄，也不是 SKILL.md.txt：

1
2

Get-ChildItem -Force -Recurse .agents\skills
Get-ChildItem -Force -Recurse (Join-Path $env:USERPROFILE '.agents\skills')

2. 檢查檔案前幾個位元組

位於 --- 前的 UTF-8 BOM（EF BB BF）可能讓嚴格解析器報告 missing YAML frontmatter delimited by ---：

1
2
3

$path = '.agents\skills\verify-build\SKILL.md'
$bytes = [IO.File]::ReadAllBytes((Resolve-Path $path))
($bytes[0..([Math]::Min(5, $bytes.Length - 1))] | ForEach-Object { $_.ToString('X2') }) -join '-'

正常前綴是 2D-2D-2D。若為 EF-BB-BF-2D-2D-2D，先備份，再轉成無 BOM UTF-8：

1
2
3
4

$resolved = (Resolve-Path $path).Path
$content = [IO.File]::ReadAllText($resolved, [Text.Encoding]::UTF8)
$utf8NoBom = [Text.UTF8Encoding]::new($false)
[IO.File]::WriteAllText($resolved, $content, $utf8NoBom)

3. 檢查 YAML 與重名

front matter 必須正確閉合，冒號後的複雜值可能需要引號。不要假設不同作用域的同名 Skill 會自動合併；應重新命名或只保留預期版本。

4. 新開會話

Skill 通常在會話啟動時發現。新增或修改後開新 Codex 會話並檢查清單；尚未確認路徑、編碼和 YAML 前，不要刪除整個設定目錄。

驗收清單

1. 路徑是 .agents/skills/<name>/SKILL.md。
2. 第一個位元組就是 ---，前面沒有 UTF-8 BOM。
3. YAML 可解析，名稱穩定、描述清楚。
4. 其他作用域沒有意外的同名 Skill。
5. 新會話能顯示並按描述觸發 Skill。

參考資料

• Codex Skills：https://developers.openai.com/codex/skills
• Agent Skills 規範：https://agentskills.io/