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

しかし新しいスレッドで実際に公開された skill は次の二つだけでした。

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 は、ファイルが front matter の区切りで始まっていないと判断し、最終的に次のエラーを出します。

`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` の先頭を認識できる形にする

最低限、次のような front matter が必要です。

---
name: your-skill-name
description: この skill が何をするものか
---

3. 新規作成または編集後は、新しいセッションを開く

skill が表示されない原因は、ファイルの問題ではなく、現在のセッション開始時に利用可能な skill 一覧がすでに確定していたことかもしれません。

そのため、セッション中に skill を作成しても、ディスク上には存在する一方で、そのセッションでは認識されない場合があります。

いちばん確実な流れは次の通りです。

skill を正しい場所に置く
現在のセッションを終了する
プロジェクトに入り直す
新しいセッションを開く
/ に表示されるか確認する

4. プロジェクト skill は事前に置いておく

プロジェクト/.codex/skills をより安定して認識させたいなら、リポジトリに入り、セッションを開始する前に、それらの skill をプロジェクト内に置いておくのが無難です。

最後に

短くまとめると：

~/.codex/skills は個人用のスキルライブラリ
プロジェクト/.codex/skills はリポジトリ用のローカルルールライブラリ
skill がディレクトリにあることと、現在のセッションに表示されることは別
表示させたいなら、正しいディレクトリに置き、正しい SKILL.md を書き、新しいセッションを開くのが基本