Codexスキルのインストール手順と確認ポイント、失敗対策

Codexスキルを導入すると何が変わるか

Codexスキルは、Codexへ毎回長い前提を説明する代わりに、特定の作業で守ってほしい手順、見るべき資料、必要な補助ファイルをひとまとまりにしておく仕組みです。コードレビュー、資料の整理、リポジトリの調査など、手順が決まっている作業ほど効果を感じやすくなります。単に回答の文体を変える設定ではなく、作業の対象と確認方法を揃えるための部品だと考えると理解しやすいでしょう。

公式の「Build skills」文書では、スキルは指示、リソース、必要に応じた補助スクリプトをまとめる形式と説明されています。Codexは最初から本文全体を読むのではなく、スキルの名前と説明を手掛かりに必要なものを選び、その後に SKILL.md を読み込みます。スキルを増やすときも、名前だけで用途が分かる説明を付けることが、狙った作業で見つけてもらうための基本になります（出典: OpenAI公式「Build skills」）。

導入方法は大きく二つです。自分のリポジトリで使う手順を固定したいなら、.agents/skills に単体のスキルを置きます。複数の能力をまとめて選びたい、デスクトップアプリやChatGPTの画面でも同じまとまりを使いたいなら、プラグインディレクトリから導入します。どちらが優れているかではなく、使う場所と共有したい範囲で選ぶのが正しい順番です。

スキルは回答を増やす仕組みではない

スキルを入れたからといって、すべての質問で長い指示が追加されるわけではありません。Codexは名前と説明を見て、依頼内容に合うときに本文を読み込みます。そのため、説明に対象作業、発動する条件、扱わない範囲を入れておくことが大切です。「開発を支援する」のように広すぎる説明より、「既存のPHP変更を読み、関連するテストを確認する」のように、作業と成果物が分かる説明の方が使い分けやすくなります。

スキル単体とプラグインは役割が違う

スキル単体は、作業手順を再利用するための最小単位です。プラグインは、複数のスキルや外部サービスとの接続などを一つの配布単位にまとめます。プラグインに含まれるスキルだけが必要なら、接続機能まで有効にする必要はありません。反対に、外部サービスの情報を読むスキルを使うなら、プラグインの説明だけでなく、どの接続が必要かと、どの操作が許可されるかを別に確認します。

2026年9月1日時点で入口を確認する理由

Codexの拡張機能は更新が続き、古い画面や旧リポジトリを前提にした説明が残りやすい領域です。OpenAIの公式リリースノートでも、2026年8月24日に codex mcp-server コマンドを非推奨とし、Codex app serverを使うよう案内しています。スキル導入そのものの手順ではありませんが、拡張の入口が変わる時期であることを示す材料です（出典: OpenAI公式リリースノート）。導入前に公式ページの現在の案内を開く習慣を付けると、旧手順との混同を減らせます。

まず配布元と形式を確認する

スキルの導入で最初に行うべきなのは、コマンドを実行することではなく、何を導入しようとしているかを確認することです。GitHub上のフォルダーがすべてそのままCodexのスキルになるわけではありません。単体のスキルなのか、プラグインの中のスキルなのか、補助ファイルが別の接続を要求するのかで、選ぶ入口と確認内容が変わります。

配布元を見るときは、公式ドキュメントのリンクからたどれるか、リポジトリに説明とライセンスがあるか、最近の更新内容を読めるかを確かめます。名前が似ているだけのコピーや、内容が読めない圧縮ファイルは、最初の導入先に向きません。公開元が公式であっても、含まれるスキルが自分の作業に必要かどうかは別に判断します。

現行のOpenAI Pluginsリポジトリは、plugins/<name>/ の下に、必須の .codex-plugin/plugin.json と、必要に応じた skills/ などを置く構成を示しています。これに対して、旧 openai/skills リポジトリは非推奨の表示になっています。古い記事にあるURLを見つけたときは、リンク先のページ自体を開き、現在の案内がどこを指しているかを確認してください（出典: openai/skillsの公式ページ）。

旧カタログをそのまま使わない

旧カタログにある導入例が、過去の時点で動いていたことと、2026年9月1日に推奨されることは同じではありません。ページに「deprecated」などの表示があれば、その表示を優先し、現行のリポジトリや公式ドキュメントへ移ります。旧ページに載っている $skill-installer の例も、対象の場所が現在も提供されているかを確かめてから扱うべきです。動かなかった場合に、Codexの不具合なのか、配布元の変更なのかを判定しやすくなります。

SKILL.mdの有無を確認する

単体のスキルなら、対象フォルダーの直下に SKILL.md があり、YAMLの先頭に name と description があることを確認します。名前だけでは、どの場面で読み込まれるか分かりません。説明の対象、含まれる参考資料、補助スクリプトの用途を読み、依頼したい作業と合うかを判断します。ファイルがあるだけで安全、正確、最新と断定せず、本文と更新履歴を読みます。

プラグインの中身を読む

プラグインは複数の部品を含む場合があるため、一覧で名前を見ただけでは内容を判定できません。plugin.jsonで名称と版を確認し、skills/にどの手順があるか、接続先があるか、画面を拡張する部品があるかを見ます。外部サービスへつながるプラグインは、読める情報と実行できる操作を区別し、導入直後は読み取り中心の作業だけで結果を確認します。現行の構造例はOpenAI Plugins公式リポジトリに掲載されています。

Codexでプラグインから導入する

プラグインを使う場合は、Codexの画面とCLIで入口が異なります。OpenAIの公式文書によれば、デスクトップアプリではPluginsタブを開き、Codex CLIでは /plugins でプラグインブラウザーを開きます。IDE拡張はプラグインの閲覧・導入先ではないため、IDEで見つからないときは不具合と決めつけず、対応している画面へ移ります。表示されるプラグインは、契約、地域、ワークスペースの設定でも変わります。

導入前後の操作と確認内容を対応させると、どこで止まったかを把握できます。

Step 1: Pluginsまたは/pluginsを開く

デスクトップアプリを使う場合はPluginsタブを開き、Codex CLIを使う場合は /plugins を入力します。検索結果が表示されないときは、先にログイン状態、使っている入口、ワークスペースの設定を確認します。CLIでプラグインブラウザーが見えることと、同じプラグインがIDE拡張にも見えることは別です。まず公式文書の対象画面と自分の画面を照合します（出典: OpenAI公式「Plugins」）。

Step 2: 詳細画面で含まれる部品を読む

名前や短い紹介だけで追加せず、詳細画面で含まれるスキル、接続するサービス、必要な設定、公開元を確認します。スキルだけのプラグインなら、作業手順の導入として読みやすい一方、接続を含むプラグインは扱うデータの範囲まで見る必要があります。似た名前のプラグインを選ぶときは、版、説明、更新日を同じ画面で比べ、目的に必要なものだけを残します。

Step 3: 導入後に新しいセッションを開始する

公式文書では、Codex CLIでマーケットプレイスからプラグインを導入した後、新しいセッションを開始してから含まれるスキルやツールを使うよう案内されています。導入ボタンを押した直後の古いセッションだけを見て「認識されない」と判定しないことがポイントです。いったんセッションを終了し、同じプロジェクトで新しく開いて、/skills で一覧を確認します。

Step 4: 小さな作業で読み込みを確かめる

最初から大きな変更を依頼せず、対象ファイルを読む、関連箇所を三つ挙げる、確認手順を説明する、といった小さな依頼を出します。スキルの説明にある手順が実際の応答へ反映され、対象外のファイルや接続へ広がっていないかを確認します。期待した名前が出ないときは、導入状態、セッションの開始時点、スキルの説明、対象プロジェクトの順に調べます。

ローカルのスキルを配置する

個人またはリポジトリ専用の手順を使いたい場合は、ローカルのスキルとして配置できます。OpenAI公式のスキル文書では、Codexは現在の作業フォルダーからリポジトリのルートまで、各階層の .agents/skills を確認すると説明されています。ユーザー領域や管理者領域にも置き場所がありますが、最初は対象リポジトリのルートに置くと、どの作業で使われるかを把握しやすくなります。

ローカル配置は、公開カタログに頼らず、自分で内容を管理できる点が利点です。一方で、フォルダー名だけでは読み込まれません。必須ファイルの名前、YAMLの形式、説明の分かりやすさ、補助ファイルの相対パスをそろえる必要があります。導入したつもりで反応しない場合は、まずファイルの場所と名前を確認します。

Step 1: .agents/skillsの下に専用フォルダーを作る

リポジトリのルートで、スキル名を表すフォルダーを作り、その直下に SKILL.md を置きます。たとえばコードレビューの確認手順なら、次のような構成です。

.agents/
└── skills/
    └── review-checklist/
        └── SKILL.md

現在の作業フォルダーがリポジトリの深い場所でも、ルートまでのどの階層に置くかで適用範囲が変わります。特定のサブフォルダーだけで使いたいなら近い場所へ、全体で使いたいならルートへ置きます。作成場所を曖昧にしたまま複数のコピーを置くと、同じ名前のスキルが二つ見えることがあるため、一つの場所から始めます。

Step 2: SKILL.mdに名前と説明を書く

公式文書が示す最小形は、YAMLの name と description、その下の指示本文です。たとえば次のように、対象と確認方法が分かる説明を先頭に置きます。

---
name: review-checklist
description: 既存コードの変更を読み、関連テストと確認漏れを整理する
---

対象ファイルを先に確認し、変更理由とテスト結果を分けて報告する。

説明を「何でも手伝う」のように広くすると、別の依頼でも選ばれる可能性が上がります。逆に対象を狭く書きすぎると、使いたい依頼で候補に出ないことがあります。作業の対象、始める条件、終わりに返す内容を一文へ入れ、本文では具体的な順番と注意点を補います。

Step 3: /skillsで一覧を確認する

Codex CLIまたはIDE拡張では /skills で一覧を開き、必要なスキルを選べます。明示して使う場合は、スキル名を示す $ の記法も公式文書に記載されています。一覧に名前、説明、場所が出ていれば、少なくとも発見の段階は通過しています。本文の指示が実際に反映されるかは、次の小さな作業で別に確かめます（出典: OpenAI公式「Build skills」）。

Step 4: 表示されない場合は再起動する

Codexがスキルの変更をすぐに一覧へ反映しない場合、公式文書は再起動を案内しています。再起動前に、SKILL.md の綴り、YAMLの区切り、フォルダーの場所、現在のプロジェクトを確認します。再起動後も出ないなら、近い階層にある別のスキルや同名の定義を一時的に外し、最小構成で見えるかを確認します。ファイルを増やすより、原因を一つずつ分ける方が早く解決できます。

初回利用の確認方法

スキルが一覧に表示された後も、すぐに本番の修正へ使うのは避けます。導入で確認できるのは、Codexがそのスキルを見つけられる状態になったことです。本文の指示が目的に合うか、補助ファイルが存在するか、対象範囲を越えないかは、実際の依頼で確認しなければなりません。導入と利用結果を別の判定にすると、表示されたことだけで安心する状態を避けられます。

確認用の依頼は、結果を人が読みやすいものにします。対象のファイル名を挙げる、既存の規約を三つ要約する、変更せずに確認項目だけ返す、といった内容なら、スキルがどこまで働いたかを比較できます。出力が期待と違っても、いきなり本文を大きく書き換えず、説明の条件、スキルの場所、使ったセッションを順に確認します。

Step 1: 表示名と場所を記録する

一覧に出た名前、説明、ファイルの場所をメモします。プラグイン経由ならプラグイン名と版、単体ならリポジトリの場所と SKILL.md の更新日を残します。同名のスキルが複数あると、どの本文が使われたかを追いにくくなります。最初の検証では一つの名前、一つの場所、一つの作業に絞ると、結果の解釈が安定します。

Step 2: 期待する手順が出力に表れるか見る

スキルに「対象を先に読む」「テスト結果と推測を分ける」と書いたなら、確認用の依頼でその区別が現れるかを見ます。すべての文言がそのまま返る必要はありませんが、重要な順番や報告形式が守られているかを確認します。説明と本文が食い違う場合は、まず本文を直す前に、どの依頼で候補として選ばれたかを見直します。

Step 3: 読み取りから変更へ範囲を広げる

読み取り結果が期待どおりなら、次は変更範囲が明確で、差分を確認できる小さな作業へ進みます。対象ファイルを一つに限定し、変更前の状態、依頼した条件、変更後の差分、確認結果を残します。外部サービスを含むプラグインでは、接続が見えたことだけで操作まで許可されたとは考えません。使う部品と作業範囲を別々に確認します。

Step 4: 公式情報と導入日を残す

スキルは本文や配布元が更新されるため、導入した日と参照した公式URLを残します。2026年9月1日時点の説明が、後日の版でも同じとは限りません。特にGitHubの配布元を使った場合は、リポジトリ名だけでなく、見たブランチや版、確認した SKILL.md の内容を記録すると、後から差分を追いやすくなります。

Codexスキルが認識されないときの切り分け

導入後にスキルが見えない原因は、入口の違い、セッションの古さ、ファイル形式、アクセス範囲のどこかにあります。いきなり再インストールを繰り返すより、どの段階まで進んでいるかを分けて確認します。プラグイン一覧にないのか、導入済みだがスキル一覧にないのか、一覧にはあるが依頼で選ばれないのかで、見る場所は変わります。

公式のプラグイン文書では、プラグインの利用可否は画面、契約、ワークスペース、地域、含まれる機能によって変わると説明されています。スキル単体とプラグインを同じ方法で直そうとせず、先に導入形態を特定します。エラーメッセージが短い場合でも、使った画面、開始した時刻、対象の名前を記録すると切り分けが進みます。

/pluginsが開けない

Codex CLIで /plugins が認識されない場合は、CLIの版、ログイン状態、利用している環境を確認します。デスクトップアプリのPluginsタブとCLIのプラグインブラウザーは、同じ名前を扱う場合でも表示や設定が異なることがあります。IDE拡張だけを開いているなら、そこではプラグインを導入できない仕様の可能性があります。公式のプラグイン文書にある対応画面へ移り、現在の版に合う入口を確認します。

導入したのにスキルが一覧にない

まず新しいセッションを開始し、/skills を開きます。それでも出ない場合は、プラグイン詳細でスキルが実際に含まれているかを確認します。プラグインには接続だけが含まれ、スキルがないものもあります。ローカル配置なら、現在の作業フォルダーからリポジトリのルートまでに .agents/skills があるか、SKILL.md の名前とYAMLが正しいかを見ます。

一覧にはあるが依頼で選ばれない

この場合は発見ではなく、説明と依頼の対応が弱い可能性があります。description に作業対象と条件があるか、本文の指示が依頼の目的と合うかを確認します。明示的にスキル名を指定して同じ小さな依頼を試し、明示時だけ動くなら説明の書き方を見直します。別のスキルが同じ対象を扱っていないかも確認し、候補を一つに絞って比較します。

古い導入コマンドが失敗する

古いガイドのコマンドが失敗したときは、入力を何度も変える前に、リンク先の公開状態を確認します。openai/skills は非推奨の表示があるため、現行の例を探すときはOpenAI PluginsとOpenAI公式プラグイン文書を基準にします。特定のスキルを導入できない場合でも、公開元の変更、プラグインの導入、スキルの読み込みを別の問題として記録すると、原因を誤認しにくくなります。

単体導入とプラグイン導入の選び方

最後に、どの導入方法が自分に合うかを整理します。単体のスキルは、内容を自分で読み、リポジトリに合わせて細かく管理したい人に向いています。プラグインは、複数のスキルや接続をまとめて探し、対応する画面で導入したい人に向いています。迷ったら、まず単体で読める小さなスキルを試し、外部サービスや複数の部品が本当に必要になった段階でプラグインを検討します。

どちらを選んでも、導入の成功は「一覧に表示されたか」だけでは判定しません。公式の説明と実際の内容が一致するか、作業の対象が予定の範囲に収まるか、結果を人が確認できるかを見ます。Codexが長い作業を扱えるようになるほど、便利な部品を増やすことより、何を任せ、どこで確認するかを決めることが重要になります。

個人の作業で使う場合

自分だけが使う確認表や調査手順なら、ローカルの .agents/skills に置く方法が分かりやすいでしょう。内容を直接読めるため、不要になったときの整理や、作業に合わせた修正も判断しやすくなります。ただし、同じ名前のスキルを別の場所へ複数置くと選択を誤りやすいため、まず一つの場所で検証します。

チームで共有する場合

複数人が同じ手順を使うなら、変更履歴、公開範囲、導入後の確認方法を一緒に決めます。プラグインを共有する場合は、含まれる接続や必要な設定が利用者ごとに異なることがあります。導入できた人の画面だけを基準にせず、別のメンバーが同じ説明を読み、同じ小さな作業を確認できるかを試します。公式ヘルプでも、プラグインの導入とアプリのアクセスは別の管理対象として説明されています（出典: OpenAI公式ヘルプ）。

導入をいったん止める場面

公開元が不明、本文を確認できない、追加される接続の範囲が分からない、期待する作業と説明が合わない、といった場合は導入を止めます。導入先が公式リポジトリでも、すべての部品を無条件に使う必要はありません。確認できる情報が増えるまで読み取りだけにとどめ、目的、公開元、版、必要な範囲を整理してから再開します。

まとめ

Codexスキルのインストールは、入口を選び、形式と公開元を確かめ、新しいセッションで読み込みを確認し、小さな作業から範囲を広げる順に進めます。2026年9月1日時点では、旧 openai/skills の扱いとプラグインディレクトリへの移行があるため、古いガイドよりもOpenAI公式のスキル文書、公式プラグイン文書、現行の公式リポジトリを優先してください。