Codex のスキル機能とは。SKILL.md で手順を再利用する
Codex に似た作業を何度も頼むと、毎回同じ前提や手順を説明し直す手間が積み重なる。その繰り返しを一度の記述で済ませるのが、2025年末に加わったスキル(Skills)機能だ。任せたい手順を SKILL.md に書いておけば、Codex は作業内容に合うときだけ読み込み、CLI でも IDE でも同じように動く。本記事ではその書き方と、Codex がスキルを使う仕組みを公式情報で整理する。
Codex のスキルは、任せたい一連の手順とその参考資料・補助スクリプトを一つの「束」にまとめた再利用の単位だ。中心になるのは SKILL.md というファイルで、先頭の YAML に name と description を書き、その下に Codex に従ってほしい手順を本文として記す。この形式は特定のツール専用ではなく、公開された共通の規格(open agent skills standard)に沿っており、同じ SKILL.md が Codex CLI・IDE 拡張・Web 版で共通に使える(出典: https://developers.openai.com/codex/skills )。
Codex はスキルをいくつかの場所から探す。作業中のフォルダ直下の .agents/skills から始まり、親フォルダ、リポジトリのルート、ユーザー個人の $HOME/.agents/skills、管理者向けの /etc/codex/skills、そして OpenAI 同梱の組み込みスキルへと、狭い範囲から広い範囲へ順にたどる。チーム共有のスキルはリポジトリに、自分専用のスキルはホーム配下に置くと、用途に応じて切り分けられる(出典: https://developers.openai.com/codex/skills )。
読み込みは賢く絞られている。Codex はまず各スキルの 名前・説明・ファイルパスだけを把握し、実際にそのスキルを使うと判断したときに初めて SKILL.md の本文を読み込む。この段階的な開示によって、スキルを増やしても会話の文脈を無駄に消費しない。$skill-creator で新しいスキルを対話的に作り、github.com/openai/skills の公開カタログから既製のスキルを取り込むこともできる。手順を「書いて、置いて、呼び出す」だけで、Codex の振る舞いを資産として積み上げられるのがスキルの要点だ(出典: https://github.com/openai/skills )。
目次 (12)
- Codex のスキルとは — 手順を SKILL.md にまとめて再利用する
- なぜ今スキルなのか — 2025年末の登場と2026年の広がり
- SKILL.md の構造 — name・description と本文
- スキルのディレクトリ構成 — scripts / references / assets
- Codex がスキルを探す場所 — リポジトリからシステムまで
- スコープの使い分け — 個人・チーム・組織
- スキルが読み込まれる仕組み — 段階的開示
- 明示呼び出しと暗黙の選択 — $スキル名 と description マッチ
- 最初のスキルを作る — skill-creator と手書き
- openai/skills カタログとインストーラ
- AGENTS.md・カスタムプロンプトとの違い — どれをいつ使うか
- まとめ — 手順を「書いて、置いて、呼び出す」
Codex のスキルとは — 手順を SKILL.md にまとめて再利用する
スキルは、Codex に任せたい作業の手順・参考資料・補助スクリプトを一つのまとまりとしてパッケージ化し、同じ作業を何度でも安定して再現できるようにする仕組みだ。公式ドキュメントはスキルを「指示・リソース・任意のスクリプトを束ね、Codex が定めた手順を確実にたどれるようにするもの」と位置づけており、その土台には特定製品に縛られない共通の規格(open agent skills standard)が置かれている。重要なのは、同じ SKILL.md が Codex CLI でもエディタの拡張(VS Code・JetBrains)でも、Web 版の Codex でも共通で機能するという点だ。つまり一度書いた手順を端末や環境ごとに作り直す必要がなく、チーム内で配って同じ振る舞いを共有できる。コード生成だけでなく、情報の収集と整理、文章作成、定型的な調査といった「説明が長くなりがちな作業」ほど、スキルにまとめておく価値が高い(出典: https://developers.openai.com/codex/skills )。
なぜ今スキルなのか — 2025年末の登場と2026年の広がり
スキルが注目を集めているのは、ここ半年ほどで土台と周辺が一気に整ってきたからだ。スキル対応は2025年12月に Codex へ加わり、年が明けてからは OpenAI 自身が公開カタログ openai/skills を整備し、すぐ使えるキュレーション済みのスキルを多数そろえてきた(出典: https://github.com/openai/skills )。配布の単位としてのプラグインまわりも継続的に強化され、Codex の更新履歴でも一覧の機械可読出力やカタログ取得の改善が記録されている(出典: https://developers.openai.com/codex/changelog )。常緑のテーマに見えて、いま改めて自分の定型作業をスキルへ落とし込む下地がそろった時期だといえる。
SKILL.md の構造 — name・description と本文
スキルの中心になるのが SKILL.md だ。ファイルの先頭には YAML 形式の前付け(フロントマター)を置き、最低限 name(スキルの名前)と description(何をするスキルかの説明)を書く。その下に、Codex に従ってほしい手順を本文として自然な文章で記述する。この二つのフィールドは単なる飾りではなく、とくに description は Codex が「いつこのスキルを使うべきか」を判断する手がかりになるため、対象とする作業と発動条件が読み取れるように具体的に書くことが肝心だ。たとえば「PR の説明文を社内テンプレートに沿って整える」「リリースノートを変更履歴から起こす」のように、対象と成果物がはっきり伝わる説明にしておくと、狙った場面で正しく選ばれやすくなる。本文には前提条件・手順・確認すべき点を順序立てて書き、迷いどころには判断基準を添えておくと、毎回の指示を省きながら品質を一定に保てる(出典: https://developers.openai.com/codex/skills )。
スキルのディレクトリ構成 — scripts / references / assets
スキルは単一ファイルにも、補助物を伴う「フォルダ」にもできる。公式ドキュメントが示す構成では、my-skill/ の直下に必須の SKILL.md を置き、必要に応じて補助スクリプトを入れる scripts/、参照資料をまとめる references/、画像やテンプレートなどの assets/、エージェント向け設定の agents/openai.yaml を任意で追加する。手順だけで完結するなら SKILL.md 一枚でよく、決まったコマンド列やテンプレートを伴うならフォルダにまとめると、関連物を一括で配布・更新できる。
Codex がスキルを探す場所 — リポジトリからシステムまで
Codex はスキルを一か所だけでなく、複数の場所から探し出す。公式ドキュメントによれば、走査は作業中のフォルダに近いところから順に広がっていく。具体的には、いま作業しているフォルダ直下の .agents/skills、その親フォルダの .agents/skills、リポジトリのルートにある .agents/skills、ユーザー個人の $HOME/.agents/skills、管理者が用意する /etc/codex/skills、そして OpenAI が同梱する組み込みスキルだ。この並びは「狭い範囲から広い範囲へ」という優先順位を表しており、プロジェクト固有の事情に合わせたスキルをリポジトリ側に、どのプロジェクトでも使いたい個人的なスキルをホーム配下に、組織標準を管理者向けの場所に、と置き分けられる。重要なのは、スキルが特定のマシン設定に閉じず、リポジトリに含めればそのままチーム全員に行き渡る点だ(出典: https://developers.openai.com/codex/skills )。
| スコープ | 場所 | 主な用途 |
|---|---|---|
| リポジトリ(作業フォルダ) | $CWD/.agents/skills |
その作業フォルダ専用のスキル |
| リポジトリ(親フォルダ) | $CWD/../.agents/skills |
入れ子のフォルダ構成 |
| リポジトリ(ルート) | $REPO_ROOT/.agents/skills |
プロジェクト全体の共有スキル |
| ユーザー | $HOME/.agents/skills |
リポジトリをまたぐ個人用スキル |
| 管理者 | /etc/codex/skills |
組織標準・既定の配布 |
| システム | 組み込み | OpenAI 同梱のスキル |
スコープの使い分け — 個人・チーム・組織
置き場所を選ぶ勘どころは、「誰にそのスキルを使ってほしいか」で決めることだ。プロジェクト固有の規約や生成物の形式に依存するスキルはリポジトリの .agents/skills に入れ、コミットして共有すればチーム全員が同じ手順を踏める。どのプロジェクトでも使う自分専用の整形・調査スキルは $HOME/.agents/skills に置けば持ち運べる。組織全体で守らせたい既定は管理者向けの /etc/codex/skills にまとめる。範囲の狭い場所ほど優先されるため、共通スキルをプロジェクト側で上書きする使い方もできる。
スキルが読み込まれる仕組み — 段階的開示
スキルをいくら増やしても会話の文脈が圧迫されないのは、Codex が「段階的開示(progressive disclosure)」という読み込み方を採るからだ。公式ドキュメントによれば、Codex はまず各スキルの名前・説明・ファイルパスだけを一覧として把握し、実際にそのスキルを使うと判断した時点で初めて SKILL.md の本文全体を読み込む。さらに、最初に提示されるスキル一覧はモデルの文脈ウィンドウのおよそ2%、ウィンドウが不明なときは8,000文字程度に収まるよう上限が設けられている。この設計のおかげで、登録したスキルが多くても入口のコストは小さく抑えられ、必要になったスキルの詳細だけが必要なタイミングで展開される。言い換えれば、description が「目次」として働き、本文が「中身」として遅れて開かれる二段構えになっている。だからこそ、説明文の質が発動精度を左右する(出典: https://developers.openai.com/codex/skills )。
明示呼び出しと暗黙の選択 — $スキル名 と description マッチ
スキルの発動には二通りある。一つは明示的な呼び出しで、プロンプトの中で $スキル名 と書くか、/skills コマンドや $ の入力からスキルを選ぶと、そのスキルを直接指名できる。もう一つは暗黙の選択で、依頼した作業内容がスキルの description と合致したとき、Codex 自身が適切なスキルを選んで読み込む。確実に使わせたい場面では指名、ふだんの作業ではモデルの判断に任せる、と場面で使い分けると無理がない(出典: https://developers.openai.com/codex/skills )。
最初のスキルを作る — skill-creator と手書き
最初の一つは、対話的に作る方法と手書きで作る方法のどちらでも始められる。手早く形にしたいなら、組み込みの $skill-creator を使うのが近道だ。何をするスキルか、いつ発動させたいか、手順の指示だけにするか補助スクリプトまで含めるか、といった問いに答えていくと、雛形ができあがる。仕組みを理解しながら作りたいなら、フォルダを切って SKILL.md を自分で書く方法でもよい。手順は次のとおりだ。
- 置き場所を決める: チーム共有ならリポジトリの
.agents/skills、個人用なら$HOME/.agents/skillsの下にスキル用のフォルダを作る。 - SKILL.md を用意する: フォルダ直下に
SKILL.mdを作り、YAML 前付けにnameとdescriptionを書く。説明は発動条件が伝わるよう具体的にする。 - 本文に手順を書く: 前提・手順・確認点を順序立てて記述する。決まったコマンドやテンプレートがあれば
scripts/やassets/に分けて添える。 - 呼び出して確かめる:
$スキル名で明示的に呼び出し、意図どおりに動くかを試す。説明文を直すと暗黙の選択精度も変わる。 - 共有して育てる: リポジトリに入れてコミットすれば、同じスキルをチーム全員が使える。使いながら手順を磨いていく。
openai/skills カタログとインストーラ
ゼロから書く前に、既製のスキルを取り込む手もある。OpenAI は公開カタログ openai/skills を用意しており、すぐ使えるスキルがそろっている(出典: https://github.com/openai/skills )。Codex 内からは $skill-installer を使ってカタログのスキルを導入でき、たとえば $skill-installer linear のように対象を指定して取り込む。まず既製スキルで使い勝手をつかみ、自分の事情に合わせて手元で書き換えていくと、立ち上がりが早い(出典: https://developers.openai.com/codex/skills )。
AGENTS.md・カスタムプロンプトとの違い — どれをいつ使うか
スキルは、AGENTS.md やカスタムプロンプトと役割が重なって見えるが、目的が異なる。AGENTS.md はプロジェクトの規約や常に守らせたい方針を書いておく場所で、対象のリポジトリで作業する限り原則として常時効く「土台のルール」にあたる(出典: https://developers.openai.com/codex/concepts/customization )。カスタムプロンプトは、よく使う指示文をあらかじめ保存して呼び出す仕掛けで、その場の依頼を短くするための定型文に近い。これに対してスキルは、手順・資料・スクリプトまで含む「持ち運べる作業の束」であり、名前と説明で発見され、必要なときだけ読み込まれる点が決定的に違う。配布の単位という観点ではプラグインが「インストールして配る容れ物」で、スキルはその中に収める「作業の書式」という関係になる。常に効かせたい方針は AGENTS.md、繰り返す定型の依頼はカスタムプロンプト、再利用したい一連の手順はスキル、と棲み分けると迷いが減る(出典: https://developers.openai.com/codex/skills )。
まとめ — 手順を「書いて、置いて、呼び出す」
Codex のスキルは、任せたい手順とその参考資料・補助スクリプトを SKILL.md を中心にまとめ、何度でも同じ品質で再現するための仕組みだ。name と description を起点に Codex がスキルを見つけ、使うと判断したときだけ本文を読み込む段階的開示によって、数を増やしても文脈を圧迫しない。置き場所は作業フォルダの .agents/skills から $HOME/.agents/skills、管理者向けまであり、共有範囲に応じて選べる。最初の一つは $skill-creator で対話的に、あるいは公開カタログ openai/skills から取り込んで始めるのが早い。常時効かせたい方針は AGENTS.md、定型の依頼はカスタムプロンプト、再利用したい手順はスキル——この棲み分けを押さえれば、毎回の説明を減らしながら Codex の振る舞いを資産として積み上げられる(出典: https://developers.openai.com/codex/skills )。
