- Codexスキルが読み込まれないとき、まず分けるべき3つの症状
- 一覧に出ない
- 自動で使われない
- 選ばれたが指示が効かない
- Codexスキルが読み込まれる仕組み
- SKILL.mdのnameとdescriptionが入口
- 明示呼び出しと暗黙的呼び出しは別物
- スキル一覧から省略される場合もある
- 最初に確認する配置パス
- リポジトリの.agents/skillsを確認
- ユーザー用の.agents/skillsを確認
- 今いる作業フォルダが合っているか
- SKILL.mdと設定を確認する
- フロントマターのname・description
- descriptionの言葉が検索意図と合っているか
- config.tomlで無効化されていないか
- agents/openai.yamlの暗黙呼び出し設定
- 変更を反映するために試すこと
- Codexを再起動する
- 新しいタスクで再確認する
- 明示呼び出しで切り分ける
- 症状別チェックリスト
- 一覧にないとき
- 一覧にはあるが自動で使わないとき
- 選ばれたのに作業へ反映されないとき
- まとめ：作り直す前に、順番に確認しよう
Codexのスキルを設定したのに、一覧に出ない。
指定しても動かない。
そんなとき、「スキルを作り直したほうが早い」と思うかもしれません。
でも、いきなり削除するのは待ってください。
Codexスキルが「読み込まれない」ように見える原因は、主に次の3つです。
- 配置場所が違う
SKILL.mdや設定が合っていない- 変更がまだ反映されていない
まずは症状を分け、配置、設定、反映の順に確認します。
スキルが読み込まれる仕組みを先に知りたい人は、Codex Skillsの仕組みと使い方も参考にしてください。
難しい操作は必要ありません。
いま起きている症状に近いところから、原因を一つずつ絞っていきましょう。
Codexスキルが読み込まれないとき、まず分けるべき3つの症状
🗨️ たかのひとことメモ
「読まない」は大きすぎる言葉。
三つに分けると、急に素直です。
最初に見るのはエラー文ではありません。
いま何が起きているかです。
症状を間違えると、確認先もずれます。
まず、近いものを一つ選びます。
表の中で、いちばん近い症状から見てみましょう。
二つありそうなら、上の行からで大丈夫です。
一覧に出ない
スキル名が一覧にありません。
この場合、まず配置を疑います。
ローカルで自作したスキルなら、まずリポジトリ側かユーザー側を確認します。
管理者・システム由来の場所も対象です。
一覧にないだけでは故障と限りません。
数が多いと、省かれる場合もあります。
先に作り直すのは遠回りです。
作業フォルダ、配置、無効化設定の順で見ます。
自動で使われない
一覧にはある。
でも、普通に頼むと選ばれない状態です。
この場合、存在は確認できています。
次はdescriptionの言葉を見ます。
依頼文と説明が離れると、選ばれにくいです。
仕事に合う言葉を前へ置きます。
明示指定で動けば、中身は読めています。
問題は自動選択側です。
選ばれたが指示が効かない
スキル名は表示される。
でも、指示どおりになりません。
ここでは、内容と反映を見ます。
保存前の内容かもしれません。
別の指示とぶつかる場合もあります。
長い依頼ほど、原因は隠れます。
新しいタスクで、一つだけ。
小さく試せば、原因が見えてきます。
Codexスキルが読み込まれる仕組み
🗨️ たかのひとことメモ
最初から全文は読みません。
玄関の表札から見る感じです。
仕組みを知ると、順番が見えます。
最初から全文は抱えません。
まず名前と説明を見ます。
必要なら、SKILL.mdを読みます。
SKILL.mdのnameとdescriptionが入口
スキルの入口はSKILL.mdです。
このファイルにnameとdescriptionを入れます。
nameはスキルの名前です。
descriptionは、いつ使うかを伝える案内板です。
案内板がぼんやりすると、選ぶ側も迷います。
仕事と使う場面を前へ書きます。
OpenAI公式のBuild skillsでも必須です。
2026年8月4日に仕様を確認しました。
更新時は公式ページも見直してください。
明示呼び出しと暗黙的呼び出しは別物
呼び出し方は二つあります。
名前を指定する方法と、自動で選ばれる方法です。
名前を指定するのが明示呼び出しです。
まず、これで反応するか試します。
普通の依頼から選ばれる。
これが暗黙呼び出しです。
descriptionが手がかりになります。
明示で動き、暗黙で動かない。
それなら配置ではなく、説明や設定を確認します。
スキル一覧から省略される場合もある
スキルが増えると、一覧も伸びます。
初期表示から省かれることも。
つまり、見えないだけでは断定できません。
明示指定で動くかも一緒に見ます。
一覧だけで決めると、削除へ走りがちです。
消えたように見えても、まだ慌てなくて大丈夫です。
でも、まずは小さく確認しましょう。
パソコンも人間も、慌てると大掃除を始めます。
明示で動かないか、一覧に出ません。
どちらも、Codexがスキルを見つけているか確認します。
そのため、次は配置確認へ進みましょう。
最初に確認する配置パス
🗨️ たかのひとことメモ
まず住所を確認します。
表札より先に家具は直しません。
一覧に出ないなら、配置からです。
Codexは、現在地から上へ探します。
どこへ置くかで、使える範囲が変わります。
自分の目的に合う場所か確認しましょう。
リポジトリの.agents/skillsを確認
特定の仕事だけで使うスキルは、リポジトリ側に置きます。
.agents/skillsを見ます。
スキルごとのフォルダを配置。
その直下に置くのはSKILL.mdです。
一段深いと、見つからない場合があります。
似た名前にも要注意。
案件ごとに分けるときに便利です。
ただし、現在地も忘れずに。
ユーザー用の.agents/skillsを確認
いろんな仕事で使うなら、ユーザー側です。
ホームフォルダの.agents/skillsを確認します。
ここなら、複数の場所で使えます。
毎回のコピーも不要です。
ただし、同じnameのスキルには注意です。
別々のスキルとして表示される場合があります。
二つあるなら、直した方を確認します。
別の方を見ていることも。
今いる作業フォルダが合っているか
配置が正しくても、現在地が違うと困ります。
別プロジェクトか確認です。
リポジトリ用は、現在地次第です。
置いた場所と、開いた場所を比べます。
Windowsは、似たフォルダが増えがちです。
OneDriveとの取り違えも起きます。
配置パスをもう少し詳しく確かめたい。
そんなときは、Codexスキルの保存場所を確認する方法も覗いてみてください。
順番は、現在地からです。
場所が合っていれば、原因をファイルの中身へ絞れます。
SKILL.mdと設定を確認する
🗨️ たかのひとことメモ
置くだけでは、まだ準備中。
名前と呼び方まで見て完成です。
配置が合っていたら、中身を見ます。
確認先はSKILL.mdと二つの設定です。
ここは一気に直さなくて大丈夫です。
一項目ずつ変えれば、原因を追いやすくなります。
フロントマターのname・description
SKILL.mdの先頭には、メタ情報があります。
三本線で囲まれた部分です。
まず、nameとdescriptionのつづりや行の形を確かめます。
nameは、区別しやすい名前に。
descriptionには、対象と場面を書きます。
基本から見直したい。
Codex Skillsを作る基本手順へ。
descriptionの言葉が検索意図と合っているか
自動選択の鍵はdescriptionです。
依頼語との距離を見ます。
たとえば「ブログ執筆」で使いたい。
それなのに説明が「文章支援」だけでは広すぎます。
対象、作業、使わない場面を短く書きます。
大事な言葉は、説明の前半へ。
ただし、キーワードの詰め込みは不要です。
人が読んで分かる説明が、いちばん強いです。
config.tomlで無効化されていないか
スキルは、削除せず無効にできます。
config.tomlの[[skills.config]]で設定します。
enabled=falseなら使われません。
一覧にないときの確認先です。
必要ならtrueへ戻すか、無効化行を見直します。
設定を変えたあとは再起動します。
ファイルを消す必要はありません。
戻せる設定から試す方が安全です。
agents/openai.yamlの暗黙呼び出し設定
openai.yamlには、追加の設定を書けます。
暗黙呼び出しはpolicy.allow_implicit_invocationで制御します。
falseなら、自動では選ばれません。
明示指定なら使えます。
OpenAI公式のBuild skillsでも、両方の設定を確認できます。
設定後は保存し、Codexを再起動してください。
これは故障ではありません。
意図して自動呼び出しを止める設定です。
自動で使いたいなら、値の見直しから。
変更後は保存し、再起動して試しましょう。
設定名が長くても、一つずつ見られたら十分です。
変更を反映するために試すこと
🗨️ たかのひとことメモ
直したのに変わらない。
保存後のひと手間が抜けがちです。
設定がすぐ反映されないことも。
古い状態かもしれません。
古い状態かもしれないときは、再起動、新しいタスク、明示指定の順で試します。
Codexを再起動する
SKILL.mdの変更は自動検出されます。
表示されないときは、再起動へ。
config.toml変更後も再起動が必要です。
保存だけでは終わりません。
再起動前に、ファイルが保存済みか確認。
未保存なら、何度起動しても同じです。
ここ、地味に効きます。
再起動は万能薬ではなく、読み直しの確認です。
新しいタスクで再確認する
ここからは、一般的な切り分け案です。
新しいタスクで同じ依頼を試し、差があるか確認します。
依頼は一つに絞りましょう。
短い入力で動きだけを確認します。
結果が変わらなくても、慌てなくて大丈夫です。
次は明示呼び出しで切り分けます。
明示呼び出しで切り分ける
最後に、スキル名を指定して試します。
これが明示呼び出しです。
明示で動けば、配置と内容は読めています。
自動選択の説明や設定へ戻ります。
明示でも動かないなら、内容側の可能性も。
配置、無効化、保存、指示、競合を見直しましょう。
一度に全部直すと、原因が消えます。
一つ変えて、一つ試す。
これで十分です。
症状別チェックリスト
🗨️ たかのひとことメモ
迷ったら、表へ戻れば大丈夫。
記憶よりチェック欄が頼れます。
ここからは、実際に手を動かす順番だけに絞ります。
自分の行だけ追えば大丈夫です。
途中で直ったら、そこで止めます。
残りを全部いじる必要はありません。
一覧にないとき
- Codexを開いた場所を見る
- .agents/skillsの位置を見る
- ファイル名がSKILL.mdか見る
- nameの重複を見る
- config.tomlの無効化を見る
- 保存して再起動する
この順番なら、住所から設定へ進めます。
ここまでで直れば、そこで確認終了です。
一覧にはあるが自動で使わないとき
- descriptionと依頼語を比べる
- 大事な用途を前半へ置く
- allow_implicit_invocationを見る
- 明示呼び出しで試す
- 新しいタスクで再確認する
明示で動けば、存在は確認済み。
あとは説明と暗黙呼び出しです。
選ばれたのに作業へ反映されないとき
- SKILL.mdの保存状態を見る
- Codexを再起動する
- 新しいタスクで試す
- 依頼を一つに絞る
- 別の指示との競合を見る
結果が同じなら、一つずつ戻ります。
迷ったら最初の行へ戻れば大丈夫です。
直す場所は、症状ごとに変わります。
近い行だけ見れば十分です。
まとめ：作り直す前に、順番に確認しよう
🗨️ たかのひとことメモ
削除より、切り分けが先です。
大掃除は最後まで取っておきます。
読まれないときは、症状を三つに分けます。
- 一覧にないなら、配置と無効化を見る
- 自動で使わないなら、説明と呼び出しを見る
- 指示が効かないなら、保存と競合を見る
次に、配置と設定を見ます。
そのあと、保存と再起動です。
一つ変えて、一つ試す。
これなら、原因を置き去りにしません。
今日直すのは、一か所で十分です。
スキル一覧に出ないと、壊れているのですか？
いいえ。配置場所が違う場合や、初期一覧から省略される場合があります。まず現在の作業フォルダと配置を確認してください。
SKILL.mdを直したら再起動が必要ですか？
変更は自動検出されます。表示や動作が変わらない場合は、保存を確認してからCodexを再起動してください。
明示指定なら動くのに、自動で使われない原因は何ですか？
descriptionの言葉が依頼と合っていないか、暗黙呼び出しが無効な可能性があります。説明とopenai.yamlの設定を確認してください。
config.tomlで無効にしたスキルは削除が必要ですか？
削除は不要です。対象スキルのenabled設定を見直し、変更を保存してからCodexを再起動してください。
明示指定しても指示が反映されないときはどうしますか？
SKILL.mdの保存状態と別ルールとの競合を確認します。新しいタスクで依頼を一つに絞ると切り分けやすくなります。