Codex Skillsの使い方｜作り方・保存場所とClaude Codeとの違い【2026年8月版】

Q: Codex Skillsはどうやって呼び出すのですか？

呼び出しは2通りあります。ひとつは明示的な呼び出しで、プロンプトの文中に $スキル名 と書いてメンションします（スキル一覧を見るには /skills）。もうひとつは自動発火で、依頼内容がスキルのdescriptionに合致するとCodexが自動で選びます。Claude Codeの /スキル名 とは記号が違う点に注意してください。Codexで使うのは $ です。

「同じ作業を頼むたびに、長い手順書きをターミナルに貼り直している」「AGENTS.mdが作業手順で肥大化して、肝心の方針が埋もれてしまった」

この記事は、そんな悩みを解決するOpenAI CodexのSkills（スキル）機能の実践ガイドです。

Skillsは、作業のやり方をフォルダ単位でCodexに預けておく仕組みです。SKILL.mdというファイルに手順を書いて所定の場所に置くと、Codexは普段それを開かずに待機し、その作業が必要になった場面でだけ中身を読み込んで、書いたとおりに動きます。

ただしこの機能、いま解説記事によって書いてあることが割れています。とくに「スキルをどこに置くか」は、公式ドキュメントと実際に配布されているCLIで内容が食い違う移行期の真っ最中で、どれか1本の記事だけを信じて置くと読み込まれないことがありえます。本記事は2026年8月時点の公式ドキュメントと、手元のcodex-cli 0.144.1での実機確認を突き合わせて、この食い違いの中身と実務的な対処まで解説します。

なお、同じSkillsでもClaude Code側の仕様や、Skillsという仕組みそのものの深掘りはClaude CodeのSkills解説にまとめています。本記事はCodex固有の話に絞ります。

この記事で身につくこと

Codex Skillsの基本と、最初から入っている同梱スキル5つ
SKILL.mdの作り方3ステップと「$スキル名」での呼び出し方
保存場所が「移行期」にある事情と、確実な置き方
agents/openai.yamlで自動発火を止める方法
Claude Code Skillsとの違い10項目
うまく動かないときのチェックポイント

Codex Skillsとは？作業手順をフォルダごと渡す拡張機能

Codex Skillsとは、SKILL.mdという手順書ファイルを中心にスクリプトや資料をフォルダにまとめ、Codexが必要な時だけ読み込む拡張機能です。

公式ドキュメントの定義はこうです。

Use agent skills to extend ChatGPT and Codex with task-specific capabilities.（エージェントスキルを使って、タスク固有の能力でChatGPTとCodexを拡張する）（出典：OpenAI公式ドキュメント）

定義に「ChatGPT」が入っているとおり、SkillsはCodex専用の機能ではありません。公式ドキュメントによれば、ChatGPTのWeb・デスクトップ・モバイル、ChatGPTデスクトップアプリ内のCodex、そしてCodex CLIで使えます。本記事では、このうちCodex（CLI・IDE拡張）での使い方を中心に扱います。

AGENTS.mdとの役割分担

Codexにはプロジェクトの指示書としてAGENTS.mdがあります（Claude CodeでいうCLAUDE.mdに当たるファイルです）。冒頭の悩み「AGENTS.mdが膨らむ」の解決策がSkillsで、役割はこう分けて考えると整理しやすくなります。

AGENTS.md：プロジェクト全体の前提・方針・禁止事項。作業の種類を問わず守ってほしいこと
Skills：特定の作業の手順書。その作業をする時だけ読んでほしいこと

「月次レポートの作成手順」「リリース前チェックの手順」のような、使う場面が限られる長い手順をSkillsに切り出せば、AGENTS.mdを方針だけのスリムな状態に保てます。

Claude CodeのSkillsと同じ規格でできている

Skillsのファイル形式である「Agent Skills」は、もともとAnthropic（Claudeの開発元）が開発し、オープン規格として公開したものです。規格の公式サイト（agentskills.io）にもその経緯が明記されており、対応クライアント一覧には「ChatGPT & Codex」が載っています。OpenAIは規格の採用側という立場です。

Claude Code SkillsとCodex Skillsは、同じ規格の別実装という関係です。SKILL.mdの基本形は共通で、後述するとおり必須項目や呼び出し方の細部が違います。規格の成り立ちや、必要な時だけ読み込む「段階的開示」という仕組みの詳細はClaude CodeのSkills解説で説明しているので、本記事では繰り返しません。

Codex Skillsの使い方【まずは同梱スキルから】

自作の前に、最初から入っているスキルを知っておくのが近道です。Codexには、OpenAIが用意したシステムスキルが5つ同梱されています。2026年8月時点、手元のWindows環境（codex-cli 0.144.1）で ~/.codex/skills/.system/ フォルダに5つとも実在することを確認しました。

最初から入っているシステムスキル5つ

スキル	役割
`skill-creator`	スキルの新規作成・更新をガイドする
`skill-installer`	公開されているスキルの一覧表示・インストール
`plugin-creator`	プラグインの作成を支援する
`imagegen`	画像の生成・編集
`openai-docs`	OpenAIの公式ドキュメントを参照して答える

skill-creatorが「最初から」使える意味

Claude Codeにも同名のskill-creatorがありますが、あちらはプラグインとして別途インストールしないと使えません。Codexは同梱なので、導入した直後から$skill-creatorと打てます。同じ名前・同じ役割のツールなのに導入手順が真逆という、両ツールを行き来する人がつまずきやすいポイントです。

明示的に呼ぶ：$スキル名をプロンプトに混ぜる

Codex CLIやIDE拡張でスキルを明示的に呼ぶには、プロンプトの中に $スキル名 と書きます。公式ドキュメントでは、/skills を実行するか $ を入力してスキルをメンションする、と案内されています（ChatGPT本体では @ を使います）。

Claude Codeのスラッシュコマンドと違い、$スキル名 は文章の中に混ぜられるのが特徴です。公式カタログにも次のような実例が載っています。

$skill-installer gh-address-comments

「$skill-creator でリリース前チェックのスキルを作って」のように、依頼文の一部としてスキル指定を埋め込む使い方ができます。/skills はあくまでスキル一覧を開くコマンドで、呼び出しの記号は $ です。

自動で呼ばれる：descriptionに合致したとき

もうひとつの呼ばれ方が自動発火です。公式ドキュメントには「依頼内容がスキルの description に合致すると、ChatGPTやCodexがそのスキルを選ぶことがある」と書かれています。毎回 $ で指定しなくても、SKILL.mdに書いた説明文と依頼が噛み合えば、Codexが自分で手順書を開いてくれるわけです。

この自動発火の精度を決めるのがdescriptionの書き方で、コツは後の章で同梱スキルを手本に説明します。

Codex Skillsの作り方【3ステップ】

ここから自作します。必要なのはフォルダ1個とテキストファイル1個だけで、プログラミングの知識は要りません。手順は次の3ステップです。

スキル用のフォルダを作る
SKILL.mdにnameとdescriptionと手順を書く
$スキル名 で呼び出して動作を確かめる

ステップ1：スキル用のフォルダを作る

置き場所には次章で説明する「移行期」の事情があるため、ここでは手元のcodex-cli 0.144.1が実際に読む ~/.codex/skills/（~ は自分のホームフォルダ）を例にします。

mkdir -p ~/.codex/skills/release-check

エクスプローラーやFinderで手動で作っても構いません。このフォルダ名（ここでは release-check）は、後述のname欄と一致させる必要があります。

ステップ2：SKILL.mdを書く

作ったフォルダの中に SKILL.md というファイルを作ります。公式ドキュメントが示す最小構成は次のとおりです（原文ママ）。

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

冒頭を --- で挟んだ部分がフロントマター（設定欄）で、Codexでは name と description の2つが必須です。公式ドキュメントに "The SKILL.md file must include name and description." と明記されています。日本語の実例に置き換えるとこうなります。

---
name: release-check
description: 本番リリース直前の最終点検を行う。ユーザーが「リリース前チェック」「デプロイして大丈夫か見て」「本番に出す前に確認して」と言ったときに使う。リリース後の障害調査や、日常のコードレビューには使わない。
---

# リリース前チェックの手順

1. 未コミットの変更と、マージし忘れているブランチが残っていないかを確認する
2. 本番用の設定ファイルに検証環境のURL・デバッグフラグ・仮の認証情報が紛れていないか洗い出す
3. 今回の変更で影響が出そうな画面と操作を、確認すべき順に並べて提示する
4. 引っかかった項目が1件でもあれば、結論「リリース見送り」を先頭に書き、理由をその下に列挙する

スクリプトや資料を同梱したい場合のフォルダ構成も公式に示されています（原文ママ）。

my-skill/
  SKILL.md (Required)
  scripts/ (Optional)
  references/ (Optional)
  assets/ (Optional)
  agents/
    openai.yaml (Optional)

必須はSKILL.mdだけで、残りは任意です。最後の agents/openai.yaml はCodex固有の設定ファイルで、後の章で説明します。

ステップ3：$スキル名で呼び出してテストする

保存したら、$release-check 今回の変更を本番に出して大丈夫か見て のように文中でメンションして呼び出してみてください。あわせて、descriptionに書いた言い回しに近い自然な文章（「リリース前チェックして」など）で頼み、自動発火するかも確認しておくと安心です。

近道：$skill-creatorにたたき台を作らせる

ゼロから書くのが不安なら、同梱の $skill-creator に頼む手があります。このスキルのdescriptionには「新しいスキルを作りたい、または既存スキルを更新したいときに使う、効果的なスキル作成のガイド」とあり、まさにこの用途のために同梱されています。$skill-creator 記事の公開前チェックをするスキルを作りたい のように、作りたい内容を添えて呼び出すところから始められます。

Codex Skillsの保存場所【2026年8月時点は移行期】

Codex Skillsの情報収集でいちばん混乱が起きているのが、この保存場所です。解説記事によって ~/.codex/skills と書いてあったり .agents/skills と書いてあったりしますが、どちらかが雑なのではなく、公式仕様そのものが移行の途中にあります。両方の状況を正確に示します。

公式ドキュメントの現行パスは「.agents/skills」系

2026年8月時点のOpenAI公式ドキュメントは、スキルを次の6つのスコープ（有効範囲）から読み込むとしています。

スコープ	パス
リポジトリ（作業フォルダ）	`$CWD/.agents/skills`
親ディレクトリ	`$CWD/../.agents/skills`
リポジトリルート	`$REPO_ROOT/.agents/skills`
ユーザー	`$HOME/.agents/skills`
管理者	`/etc/codex/skills`
システム	Codexに同梱（OpenAI提供）

$CWD は現在の作業フォルダ、$REPO_ROOT はリポジトリの最上位、$HOME はホームフォルダのことです。ドキュメント上の正解は「.agents/skills 系に置く」になっています。

実際に配布されているCLIは「~/.codex/skills」を見る（実機検証）

ところが、手元のcodex-cli 0.144.1（npmでインストールしたWindows環境・2026年8月時点）を検証すると、結果はドキュメントと食い違いました。

実行ファイル内を文字列検索しても、.agents/skills という文字列は1件も存在しない
代わりに $CODEX_HOME/skills（既定では ~/.codex/skills）への言及が複数ある
同梱の skill-installer の説明書きにも "Installs into $CODEX_HOME/skills/<skill-name> (defaults to ~/.codex/skills)." と明記されている
実際にシステムスキル5つも ~/.codex/skills/.system/ に置かれている

どちらか一方だけを信じると読み込まれないことがある

公式ドキュメントだけを信じて ~/.agents/skills に置くと、0.144.1のようなCLIでは読み込まれない可能性があります。逆に「~/.codex/skills に置けばよい」という解説は、ドキュメント上はすでに古い書き方です。どのバージョンで新パスへの移行が完了するのか（したのか）は、公式チェンジログからは特定できていません（2026年8月時点・未確認）。

実務的な結論：バージョンを確認、迷ったら両方に置く

移行期の今、確実に動かすための手順は次のとおりです。

まず codex --version で自分のバージョンを確認する
筆者が確認した0.144.1では、個人用スキルは ~/.codex/skills/ が確実です（同梱スキルが現にそこにあります）。他の版がどちらを読むかは未確認です
判別が面倒なら、両方のパスに置くか、シンボリックリンク（フォルダの参照を共有する仕組み）で1箇所の実体を両方から見えるようにする

新しく置いたスキルが認識されない時は、まず配置パスを疑ってください。この食い違いはいずれCLI側の更新で解消されていくはずなので、本記事も動きがあれば追記します。

SKILL.mdの書き方：nameとdescriptionのルール

必須の2項目には、Agent Skills規格（agentskills.io/specification）で細かい制約が決められています。バリデーションエラーの原因になりやすいので、先に押さえておきましょう。

nameの制約は意外と厳しい

最大64文字
使えるのは小文字の英数字とハイフンのみ
ハイフンで始まる・終わるのは不可。連続ハイフン（--）も不可（規格の無効例：pdf--processing）
親フォルダの名前と一致させることが必須（規格原文："Must match the parent directory name"）

とくに最後の「フォルダ名と一致」は見落としやすく、フォルダをリネームしたのにnameを直し忘れる事故が起きがちです。なお一部の解説記事には「nameは100文字以内」といった異なる数字が載っていますが、2026年8月時点の規格では上記のとおり64文字です。

descriptionは「使う時」と「使わない時」を書く

descriptionは1〜1024文字で、自動発火の判定材料になる最重要フィールドです。注目したいのは、公式の最小構成サンプルにある説明文です。

Explain exactly when this skill should and should not trigger.（このスキルがいつ発火すべきで、いつ発火すべきでないかを正確に書く）

「使うべきでない時」まで書けと明示しているのがCodex公式の特徴です。同梱のimagegenがちょうど良い手本で、descriptionの前半で「写真・イラスト・テクスチャなどのビットマップ画像を新規生成する時に使う」と使いどころを挙げたあと、後半で "Do not use when the task is better handled by editing existing SVG/vector/code-native assets…"（既存のSVGやベクター素材の編集で済むタスクには使わない）と除外条件まで書いています。

自作するときも、この「使う時＋使わない時」の2段構成に、ユーザーが実際に言いそうな言葉（「リリース前チェックして」など）を加えるのが基本形です。

scripts・references・assetsと「500行ルール」

SKILL.mdと同じフォルダには、実行スクリプト（scripts）、参考資料（references）、テンプレートなどの素材（assets）を同梱できます。規格のガイドラインでは、SKILL.md本体は500行以下に保ち、詳細な資料は別ファイルへ移すことが推奨されています。読み込みは段階的で、常時読まれるのはnameとdescriptionのメタデータ（1スキルあたり約100トークン）だけ、本文は発火時（5,000トークン未満推奨）、同梱資料は必要になった時だけです。

この「段階的開示」の仕組みと、トークン消費の考え方の詳細はClaude CodeのSkills解説で扱っています。規格が同じなので、考え方はCodexにもそのまま当てはまります。ちなみに同梱の5スキルもSKILL.md単体ではなく、5つすべてが scripts・assets・agents を、うち4つは references まで備えたフル構成でした（実機で確認）。

agents/openai.yamlでCodex独自の設定をする

Agent Skills規格にはない、Codexならではの拡張がこの agents/openai.yaml です。スキルフォルダの中に agents フォルダを作り、その中に置く任意の設定ファイルで、公式ドキュメントに設定項目が列挙されています。Claude Codeが拡張設定をSKILL.mdのフロントマターに集約するのと対照的に、Codexは規格外の設定を別ファイルに分離する設計です。

勝手に発火させない：allow_implicit_invocation

実務でいちばん需要が大きいのがこれです。「便利だけれど、Codexの判断で勝手に走られたら困る」というスキル（公開処理・送信処理など）には、agents/openai.yaml に次の2行を書きます。

policy:
  allow_implicit_invocation: false

policy: の下にぶら下げる形が公式の書式です。allow_implicit_invocation をトップレベルに直書きした形は、公式ドキュメントのサンプルにも、Codex同梱スキルの実物にも見当たりません（後述の全体像を参照）。

これで自動発火が止まり、$スキル名 で明示的に呼んだ時だけ動くようになります。既定値はtrue（自動発火する）なので、止めたい場合だけ書けば大丈夫です。この設定項目が0.144.1の実行ファイル内にも存在することは実機で確認済みで、公式ドキュメント・配布版CLIの両方にある機能です。

Claude Codeでは書く場所も値の向きも違う

同じ「自動発火を止める」でも、Claude CodeではSKILL.mdのフロントマターに disable-model-invocation: true と1行書くだけです。Codexは別ファイル（openai.yaml）を作り、その policy: の下に allow_implicit_invocation: false と書きます。目的は同じなのに、書く場所もキーの階層も違い、trueとfalseの向きまで逆です。両方使う人は混同しやすいので注意してください。

表示名・説明・見た目のカスタマイズ

公式ドキュメントによれば、openai.yamlでは他に次の項目を設定できます。いずれも interface: の下にぶら下げる項目です。

display_name：ユーザーに見せる表示名
short_description：ユーザーに見せる短い説明
icon_small / icon_large / brand_color：アイコンとブランドカラー
default_prompt：スキル選択時に流し込む既定のプロンプト

MCPサーバーに依存するスキル：dependencies.tools

スキルが外部ツールとの接続（MCPサーバー）を前提にしている場合は、dependencies: の tools: で依存を宣言できます。実機の codex features list でも、MCP依存スキルの自動インストールに関する機能フラグ skill_mcp_dependency_install がstable（正式機能）として有効になっていることを確認しました（0.144.1）。MCPという仕組み自体の説明はMCPの解説記事をどうぞ。プロトコルはツール共通なので、考え方はCodexでも同じです。

openai.yamlの全体像

ここまでの3ブロックをまとめると、openai.yamlの構造はこうなります。interface / dependencies / policy という3つのトップレベルキーがあり、各設定はその下に入る、という形です。

interface:
  display_name: "リリース前チェック"
  short_description: "本番リリース直前の最終点検をまとめて実行"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Use $release-check to review the pending release before deploying."

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

policy:
  allow_implicit_invocation: false

必要な項目だけ書けば十分で、全部埋める必要はありません。実際、0.144.1に同梱されている5つのシステムスキルはいずれも agents/openai.yaml を持っていましたが、中身は interface: ブロックだけ（openai-docsのみ dependencies: も併記）というシンプルな構成でした（実機で確認）。

Claude Code Skillsとの違い【10項目比較表】

同じ規格の別実装なので「SKILL.mdを書いてフォルダに置く」という基本は共通ですが、日常の操作感に効く違いが積み重なっています。2026年8月時点の両者を10項目で比べます（Claude Code側の仕様の裏付けはClaude CodeのSkills解説を、Claude Codeというツール自体を知らない方はClaude Codeとはをご覧ください）。

#	項目	Codex	Claude Code
1	規格との関係	Agent Skills規格の採用側	規格の発案元（Anthropic）
2	明示呼び出しの記号	`$skill-name`（文中にメンション）。一覧は `/skills`	`/skill-name`（スラッシュコマンド）
3	フロントマターの必須項目	`name` と `description` が必須	全フィールド任意（`description` のみ推奨）
4	拡張設定の置き場所	別ファイル `agents/openai.yaml`	SKILL.mdのフロントマターに集約
5	自動発火の止め方	`policy.allow_implicit_invocation: false`（openai.yaml）	`disable-model-invocation: true`（フロントマター）
6	スキル作成支援ツール	`$skill-creator` が同梱・すぐ使える	`/skill-creator` はプラグインで要インストール
7	スキルの導入手段	`$skill-installer` が同梱	`/plugin install` コマンド
8	個人用スキルの置き場所	`~/.codex/skills`（0.144.1実測）※公式ドキュメントは `~/.agents/skills`	`~/.claude/skills/`
9	プロジェクト指示書	AGENTS.md	CLAUDE.md
10	公式カタログ	`openai/plugins`（`openai/skills` は非推奨化）	`anthropics/skills`・公式マーケットプレイス

いちばん体感差が大きいのは呼び出し記号

Claude Codeの /skill-name は、スラッシュコマンドとしてスキルを起動する操作です。対してCodexの $skill-name はメンションで、「$skill-installer で新しいスキルを探して」のように依頼文の中に埋め込めます。記号の違いは小さく見えて設計思想の違いで、Codexではスキル指定と依頼内容をひとつの文に混ぜて書けます。両方使う人がやりがちなのが記号の取り違えで、Codexで使うのは $、/skills は一覧表示だと覚えてください。

frontmatterの必須要件が真逆

Codex（およびAgent Skills規格）は name と description が必須。一方Claude Codeは全フィールド任意で、name を省略するとフォルダ名が表示名になります。「同じ規格なのに？」と思うかもしれませんが、Claude Codeは規格より緩い受け入れ方をしている実装、Codexは規格どおり必須にしている実装、という関係です。この非対称が次の「持ち込み問題」につながります。

Claude Codeで作ったSKILL.mdはCodexで使える？

基本的に使えます。ただし落とし穴が1つあります。Claude Codeでは name を省略した（あるいはdescriptionすら書いていない）SKILL.mdが正常に動くため、そのままCodexに持ち込むと必須要件を満たさず弾かれる可能性があります。移す前に次を確認してください。

Claude Code産SKILL.mdの持ち込み前チェック

フロントマターに name があるか（フォルダ名と一致・小文字英数字とハイフンのみ・64文字以内）
description があるか（1〜1024文字）
disable-model-invocationなどClaude Code固有の設定に頼っていた場合、Codex側では agents/openai.yaml で設定し直す

逆方向（Codexで作ったSKILL.mdをClaude Codeへ）は、Claude Code側に必須要件がないため、基本的にそのまま通ります。

両方使うなら置き場所の共通化を検討

Claude CodeとCodexを併用するなら、同じSKILL.mdを2箇所にコピーして二重管理するより、どちらかのスキルフォルダを正として、もう一方からシンボリックリンクで参照する運用が管理しやすくなります。保存場所の章で紹介した移行期対策と同じ発想です。修正が1箇所で済むので、スキルが増えてきた段階で効いてきます。

Skills・AGENTS.md・Custom Prompts・MCPの使い分け

Codexの周辺には「Codexに何かを覚えさせる・つなげる」仕組みが複数あり、初めての方はここで混乱しがちです。役割を1枚の表にまとめます。

仕組み	一言でいうと	向いているもの
AGENTS.md	プロジェクトの指示書	常に守ってほしい前提・方針・禁止事項
Skills	作業の手順書	特定タスクの手順。必要な時だけ読ませたいもの
Custom Prompts	定型文のテンプレート	毎回ほぼ同じ文面で送る指示
MCP	外部サービスへの接続口	データベース・ブラウザなど、Codexの外の道具とのやり取り

SkillsとCustom Promptsの線引きは、実践者の間で「Skillsは作業のやり方（How-to）を教えるもの、Custom Promptsは送る文面（テンプレート）を保存するもの」と整理されています。手順や判断基準まで含むならSkills、決まり文句の再利用ならCustom Promptsです。

MCPとSkillsは競合しません。MCPが「接続」、Skillsが「手順の知識」なので、「MCPでスプレッドシートにつなぎ、Skillsの手順書どおりに月次集計する」のように組み合わせて使います。CodexにMCPサーバーを設定する具体的な手順はCodexのMCP設定解説にまとめました。

公開スキルを導入する：$skill-installerとカタログの現状

自作だけでなく、公開されているスキルを取り込むこともできます。ここにも「ドキュメントとCLIの二重状態」がもうひとつあるので、あわせて説明します。

$skill-installerの使い方

同梱の $skill-installer は、その説明書きに「キュレーション済みリスト、またはGitHubリポジトリのパスから $CODEX_HOME/skills にCodexスキルをインストールする。インストール可能なスキルの一覧表示や、他リポジトリ（プライベート含む）からの導入を頼まれた時に使う」とあるとおり、スキル導入の窓口役です。公式カタログには $skill-installer gh-address-comments のように、スキル名を添えて頼む実例が載っています。「入れられるスキルを一覧して」とだけ頼むところから始めても大丈夫です。

注意：openai/skillsリポジトリは非推奨化済み

多くの解説記事がスキルの入手先として github.com/openai/skills を案内していますが、このリポジトリは現在deprecated（非推奨）です。リポジトリ本文に "This repository is deprecated. For current Codex skill and plugin examples, use the OpenAI Plugins repository." と明記されており、現行の公式サンプルは github.com/openai/plugins に移りました。移行先では各プラグインが plugins/<名前>/ 以下に置かれ、その中に skills/ を含められる構造です。

ここでも「ドキュメントとCLIの二重状態」が起きている

非推奨化された一方で、codex-cli 0.144.1に同梱されているskill-installerの説明書きは、今も旧リポジトリ（openai/skills）のキュレーションリストを参照先としています（実機のSKILL.md記載で確認）。当面は「新しくスキルを探すならopenai/plugins、$skill-installerの一覧は旧カタログ由来」と押さえておくと混乱しません。

入れる前のセキュリティチェック3点

スキルは指示とスクリプトでCodexの動きを変えるものなので、他人が作ったスキルの導入はソフトウェアのインストールと同じ心構えで扱ってください。最低限のチェックは3つです。

SKILL.mdを読む：説明文と実際の指示内容が一致しているか
scriptsフォルダの中身を読む：同梱スクリプトが何を実行するのか
外部URLへのアクセスがないか見る：取得内容に想定外の指示が混ざるリスクがあるため

うまく動かないときのチェックリスト

最後に、つまずきやすいポイントを症状別にまとめます。

スキルが一覧に出てこない

配置パスを確認する：本記事の保存場所の章のとおり、移行期のパス違いが最有力の原因です。~/.codex/skills/ と ~/.agents/skills/ の両方に置いて切り分けてみてください
フォルダ名とnameの一致を確認する：規格上、name は親フォルダ名と一致が必須です
ファイル名を確認する：手順書のファイル名は SKILL.md です

自動で発火しない

descriptionを具体的にする：「便利なツール」のような曖昧な説明では照合できません。「使う時」の言い回し（ユーザーが実際に言う言葉）を入れてください
allow_implicit_invocationを確認する：agents/openai.yaml の policy: 配下で false にしていると、自動発火はしません
まず $スキル名 で明示的に呼んでみる：明示で動くなら、スキル自体は認識されており、descriptionの照合だけが課題だと切り分けられます

バリデーションエラーになる

name の制約違反が定番です：大文字を使っている・連続ハイフン・64文字超・フォルダ名と不一致
description が空、または1024文字を超えている
Agent Skills規格には公式の検証ツールがあり、skills-ref validate ./my-skill で機械チェックできます（規格リポジトリで提供）

よくある質問（FAQ）

Q1. Codex SkillsのSKILL.mdはどこに置けばいいですか？

公式ドキュメント（2026年8月時点）は .agents/skills 系のパス（作業フォルダ・リポジトリルート・ホームの各スコープ＋管理者用の /etc/codex/skills）を案内しています。ただし同時点で配布されているCLIには ~/.codex/skills を読む版が残っており、手元のcodex-cli 0.144.1の実行ファイルに .agents/skills という文字列は存在しませんでした。まず codex --version で自分の版を確認し、判別が面倒なら両方に置くか、シンボリックリンクで1箇所を共有するのが確実です。

Q2. Codex Skillsはどうやって呼び出すのですか？

呼び出しは2通りあります。ひとつは明示的な呼び出しで、プロンプトの文中に $スキル名と書いてメンションします（スキル一覧を見るには /skills）。もうひとつは自動発火で、依頼内容がスキルのdescriptionに合致するとCodexが自動で選びます。Claude Codeの /スキル名とは記号が違う点に注意してください。Codexで使うのは $ です。

Q3. Claude Codeで作ったSKILL.mdをCodexでそのまま使えますか？

同じAgent Skills規格なので基本的に使えます。ただしClaude Codeはnameを省略できるのに対し、Codexはnameとdescriptionが必須です。nameはフォルダ名と一致・小文字英数字とハイフンのみ・64文字以内という制約もあるため、移す前にこの2項目が揃っているか確認してください。逆方向（Codexで作ったスキルをClaude Codeへ）は、必須要件が緩いため基本的にそのまま通ります。

Q4. スキルが勝手に発火しないようにできますか？

できます。スキルフォルダ内に agents/openai.yaml を作り、policy: の下に allow_implicit_invocation: false と書くと、$スキル名で明示的に呼んだ時だけ動くようになります。トップレベルに直書きする形は公式サンプルにないのでご注意ください。既定値はtrue（自動発火する）です。Claude Codeで同じことをする場合は、SKILL.mdのフロントマターに disable-model-invocation: true と書きます。

Q5. Codex Skillsは無料で使えますか？

Skillsはローカルにフォルダとファイルを置くだけの機能で、アップロードもAPIキーも不要です。Skills機能そのものへの追加課金があるという公式記述は確認できていません（2026年8月時点）。ただしトークンは消費します（規格上、待機中はスキル1個あたり約100トークン、発火時に本文5,000トークン未満が目安）。Codex本体については、公式の料金ページに "ChatGPT Work and Codex are included in your ChatGPT Free, Go, Plus, Pro, Business, Edu, or Enterprise plan"（CodexはChatGPTのFree・Go・Plus・Pro・Business・Edu・Enterpriseの各プランに含まれる）と明記されています。送れるメッセージ数は使うモデル・タスクの規模と複雑さ・ローカル実行かクラウド実行かで変わるとされているので、プランごとの上限はOpenAI公式の料金ページでご確認ください。トークン消費の考え方はClaude Codeの料金解説で説明している仕組みと共通です。

まとめ：Codex Skillsは「置き場所」さえ外さなければ迷わない

この記事の要点

Codex Skillsは、SKILL.md＋資料一式をフォルダで渡す手順書機能。ChatGPTとCodexの共通機能で、Agent Skills規格（Anthropic発）のOpenAI実装
skill-creatorなどシステムスキル5つが最初から同梱。呼び出しは文中の $スキル名メンション
保存場所は移行期。公式ドキュメントは .agents/skills 系、0.144.1のCLIは ~/.codex/skills。迷ったら両方に置く
nameとdescriptionは必須。nameはフォルダ名と一致・64文字以内、descriptionは「使う時」と「使わない時」を書く
自動発火の制御は agents/openai.yaml の policy.allow_implicit_invocation（既定true）
openai/skillsは非推奨化済み。現行カタログは openai/plugins

最初の1個は、手順がすでに頭に入っている定番作業から選ぶのが確実です。何度も繰り返している作業なら、いつもの段取りをそのまま書き出すだけで手順書になります。Claude Codeも併用している方は、nameとdescriptionさえ揃えておけば、同じSKILL.mdが両方のツールで動きます。

Claude Code側のSkillsの仕様や、段階的開示・セキュリティといった仕組みの深掘りはClaude CodeのSkills解説で扱っています。Codexは仕様の動きが速い時期なので、本記事の内容は「2026年8月時点（codex-cli 0.144.1で確認）」である点を踏まえつつ、手元では codex --version からの確認を習慣にしてください。