Codex Skillsとは？SKILL.mdの書き方と配置場所・チーム展開の注意点【2026年】

AIに同じ指示を毎回書き直している状態から抜け出す仕組みとして、Codex Skillsが注目されています。業務の手順を一度フォルダにまとめておけば、依頼の内容に応じてCodexが自動的に読み込み、同じ品質で実行できるようになります。

この仕組みはOpenAI独自のものではなく、オープンな規格として公開されているものです。Claude CodeやGitHub Copilot、Cursorなど複数のエージェントが同じ形式を採用しており、書いた資産を他の環境でも使える設計になっています。

本記事では、公式ドキュメントをもとにSkillsの仕組みとSKILL.mdの構造を整理したうえで、6つの配置場所を使ったチーム展開の設計、そして見落とされやすい制約までを扱います。作り方の手順だけでなく、業務ナレッジとしてどう運用するかまで踏み込んだ内容です。

確認したいポイント	結論	詳細
Codex Skillsとは何か？	作業手順を再利用する仕組み	指示書とスクリプトをフォルダにまとめ、Codexが必要な場面で自動的に読み込んで実行します。
どう呼び出される？	明示指定と自動判断の2通り	記号を使って直接指定する方法と、依頼内容が説明文と一致したときに自動で選ばれる方法があります。
作るのは難しい？	対話形式で作成できる	専用の作成支援機能に答えていくだけで組み立てられます。操作を実演して記録する方法もあります。
注意すべき点は？	増やしすぎると発動しなくなる	起動時に読み込む一覧には上限があり、数が多いと説明が短縮され、一部は省略されます。

この記事でわかること

・Codex Skillsの位置づけと、AGENTS.mdやMCPとの役割の違い

・段階的に読み込む仕組みと、スキルを増やしすぎたときの制約

・SKILL.mdの構造と、公式が示している書き方の要点

・6つの配置場所と、チームで共有する際のスコープ設計

・業務ナレッジとして運用する際の統制と、更新の考え方

AIエージェントの業務活用について、導入の進め方と支援内容をまとめた資料をご用意しています。 社内での検討材料としてご活用ください。 ▶ 資料請求はこちら

Codex Skillsとは作業手順を再利用する仕組み

まず位置づけを整理します。プロンプトを保存しておく機能と混同されやすいのですが、動作の仕組みも扱える内容も異なります。

スキルが担う役割

Skillsは、特定の作業に必要な指示、参考資料、必要に応じたスクリプトを1つのフォルダにまとめ、AIが必要な場面で使えるようにする仕組みです。

OpenAIの公式ドキュメントでは、スキルは再利用可能なワークフローを記述するための形式と説明されています。手順を書いた文書と、それを実行するための材料をセットで渡す形になります。

毎回長い指示文を書き直す必要がなくなるだけでなく、誰が依頼しても同じ手順で処理されるようになります。個人の工夫を組織の資産に変えるという意味で、単なる時短の道具とは位置づけが異なります。

オープンな標準規格として広がった

この形式はOpenAI独自のものではありません。もともとAnthropicのClaudeの拡張機能として登場し、2025年12月にオープンな標準として公開されたという経緯があります。

現在はClaude Code、GitHub Copilot、VS Code、Cursor、OpenAI Codex、Gemini CLIなど、多くのエージェントが同じ形式を採用しています。特定分野の知識を外部化してパッケージ化する手法として、業界の共通仕様になりつつあります。

この点は実務上の意味が大きくなります。1つのツールに合わせて書いた資産が、そのツールの都合で使えなくなるリスクを下げられるためです。ツールの乗り換えを想定するなら、この規格に沿って書いておく価値があります。

使える環境

公式の説明によると、単体のスキルはChatGPTのデスクトップアプリ、Codex CLI、IDE拡張で利用できます。プラグインとしてまとめられたスキルは、さらに幅広い環境で使えます。

プラグインにバンドルした場合は、ウェブ、デスクトップ、モバイルのChatGPTでも利用可能になります。自分で使うだけなのか、他の人に配布するのかで、選ぶべき形式が変わります。

デスクトップアプリでは、サイドバーからスキルの一覧を確認できます。どのプロジェクトでどんなスキルが作られているかを俯瞰できるため、重複の確認にも使えます。

何が変わるのか

導入の効果は、作業時間の短縮だけではありません。出力のばらつきが減ることによる品質の安定が、実務では大きく効きます。

OpenAI自身の事例では、自社のSDKリポジトリでスキルと設定ファイル、CI連携を組み合わせた結果、3か月間でマージしたプルリクエストが316件から457件へ増加したと報告されています。検証、リリース準備、レビューといった繰り返し作業を再現可能な形にした結果です。

この数字が示しているのは、個々の作業が速くなったというより、同じ作業を毎回設計し直す手間がなくなったという変化です。開発以外の業務でも同じ構造が当てはまります。

関連記事：Codex CLIの使い方｜インストール手順と基本コマンド・承認モードの設定を解説

仕組みを理解する

使いこなすうえで、内部でどう扱われているかを知っておくと判断が変わります。とくに読み込みの仕組みは、後述する制約に直結します。

段階的に読み込む設計

スキルが増えても動作が重くならないよう、情報は段階的に読み込まれる設計になっています。すべてを最初から読むわけではありません。

起動時に把握するのは、各スキルの名前と説明文、そしてファイルの場所だけです。実際にそのスキルを使うと判断した時点で、SKILL.mdの全文を読み込みます。さらに必要があれば、同梱された参考資料も読みます。

この設計により、多数のスキルを入れておいても普段の動作に影響しにくくなっています。ただし、次に説明する上限が存在する点は押さえておく必要があります。

起動時の一覧には上限がある

見落とされやすいのがこの制約です。起動時に読み込むスキルの一覧には、使用できる分量の上限が設けられています。

公式ドキュメントによると、この一覧はモデルのコンテキストウィンドウの最大2％まで、コンテキストウィンドウが不明な場合は8,000文字までとされています。プロンプト全体を圧迫しないための設計です。

スキルが多い場合、まず説明文が短縮されます。それでも収まらない場合は一部のスキルが一覧から省略され、警告が表示されます。つまり、作りすぎると意図したスキルが発動しなくなる可能性があるということです。

2つの呼び出され方

スキルの発動には2つの経路があります。1つが明示的な呼び出しで、記号を使って直接指定します。ChatGPTではアットマーク、Codexではドル記号を使うか、専用のコマンドで一覧から選びます。

もう1つが暗黙的な呼び出しです。依頼の内容がスキルの説明文と一致すると判断された場合、指定しなくても自動的に選ばれます。日常的に使うのはこちらで、うまく機能するかどうかが実用性を左右します。

確実に使いたい場面では明示的に指定し、普段は自動判断に任せるという使い分けが現実的です。重要な処理ほど、明示指定を前提にした運用にしておくと事故を防げます。

説明文の書き方が精度を決める

暗黙的な呼び出しは説明文との一致で判断されます。そのため、説明文の質がそのまま発動精度になります。

公式でも、適用範囲と境界を明確にした簡潔な説明を書くこと、そして主要な用途とトリガーとなる語を前のほうに置くことが推奨されています。説明が短縮されても一致できるようにするためです。

書くべきは、何をするスキルかだけではありません。どんなときに使うべきか、そして使うべきでないかまで含めると、誤った場面での発動を減らせます。

どの業務をスキル化すべきか、チームでどう共有すべきかでお悩みの場合は、無料の個別相談をご利用ください。 ▶ 相談予約はこちら

関連記事：Codex CLIのインストール方法｜Mac・Windows・Linux別の手順と認証・エラー対処

SKILL.mdの構造と書き方

ここからは実際の作り方に入ります。構造自体は単純で、必須の要素は多くありません。

フォルダの構成

スキルは1つのフォルダとして表現されます。必須なのはSKILL.mdというファイル1つだけで、あとは必要に応じて追加します。

任意で置けるのは、実行可能なコードを入れるscripts、参考資料を入れるreferences、テンプレートなどを入れるassetsの3つです。さらに、表示名や依存関係を設定するための設定ファイルを置く場所も用意されています。

最初から全部を用意する必要はありません。公式でも、決定的な動作や外部ツールが必要でない限り、スクリプトより指示を優先するよう推奨されています。まずは指示だけで作り、足りなければ足す進め方が適しています。

必須の2項目

SKILL.mdの先頭には、設定情報を書く領域があります。ここに必須なのは名前と説明文の2つだけです。

名前は識別のために使われ、説明文は発動の判断に使われます。どちらも1行で簡潔に書く必要があり、文字数にも上限が設けられています。

とくに説明文は、先ほど述べたとおり発動精度に直結します。ここを曖昧に書くと、必要な場面で呼ばれない、あるいは関係ない場面で呼ばれるという問題が起きます。

本文に書くべきこと

設定情報の下には、実際にAIが従う手順を書きます。ここは通常の文書と同じ形式で自由に書けますが、書き方によって結果が変わります。

公式が推奨しているのは、明示的な入力と出力を伴う命令形のステップで書くことです。「〜してください」ではなく「〜する」という形で、順番に並べる書き方が適しています。

どこまで自由度を許すかも設計の対象です。厳密な手順が必要な作業では細かく指定し、判断の余地を残したい作業では方針だけを示すという書き分けが有効になります。

任意のメタデータ

設定ファイルを追加すると、表示上の名前やアイコン、色などを指定できます。デスクトップアプリで一覧に表示される際の見え方に関わる部分です。

実務上より重要なのが、暗黙的な呼び出しを許可するかどうかの設定です。この項目を無効にすると、自動判断では発動せず、明示的に指定した場合のみ動作するようになります。

誤って発動すると影響が大きい処理では、この設定を使って明示指定のみに限定してください。外部への送信を伴う処理や、データを書き換える処理が該当します。

公式が示す4つの要点

公式ドキュメントには、作成時の要点が4つ挙げられています。いずれも実務で効いてくる内容です。

1つ目が、各スキルを1つの仕事に絞ること。2つ目が、スクリプトより指示を優先すること。3つ目が、明示的な入力と出力を伴う命令形で書くこと。そして4つ目が、説明文に対してプロンプトをテストし、意図したとおりに発動するか確認することです。

とくに4つ目は省略されがちですが、暗黙的な呼び出しに頼る以上は欠かせません。想定する依頼文をいくつか用意し、実際に発動するかを確かめてから共有してください。

関連記事：Codex VSCode拡張の使い方｜インストール手順と基本操作・CLIとの違い

スキルの作り方

作成方法は複数用意されており、状況に応じて選べます。ゼロから書く必要はありません。

対話形式で作る

最も手軽なのが、組み込みの作成支援機能を使う方法です。専用の記号を付けて呼び出すと、質問に答えていく形でスキルを組み立てられます。

尋ねられるのは、このスキルが何をするのか、どんなときに発動すべきか、スクリプトを含めるかどうかの3点です。なお、指示のみで作るのが既定の動作とされています。

自分でも手順が整理できていない段階では、この対話が思考の整理にもなります。何を自動化したいのかが曖昧なまま書き始めるより、質問に答えるほうが早く形になります。

操作を記録して作る

手順を説明するより実際にやって見せるほうが早い場合は、操作を記録する機能が使えます。一連の作業を記録し、その内容をもとにスキルの下書きが作られます。

言語化しにくい作業ほど、この方法が向いています。画面上の操作を伴う手順や、複数のツールをまたぐ作業は、文章で書き起こすと抜けが生じやすい領域です。

生成された下書きはそのまま使うのではなく、不要な操作を削り、判断の理由を書き足してから確定させてください。記録だけでは、なぜその手順なのかが残りません。

手作業で作る

既に手順が固まっている場合は、フォルダを作ってSKILL.mdを置くだけでも構いません。名前と説明文を書き、その下に手順を並べれば完成します。

Codexはスキルの変更を自動で検出する仕組みになっています。反映されない場合は再起動すると認識されます。編集して試すという繰り返しが行いやすい設計です。

既存の社内文書がある場合は、それを土台にするのが早道です。作業手順書やチェックリストが整備されているなら、形式を整えるだけでスキルになります。

既存のスキルを取り込む

自分で書かずに、公開されているものを導入する方法もあります。専用のインストール機能を使うと、キュレーションされたスキルを追加できます。

ただし公式では、この方法はローカルでのセットアップと試用に適しているとされ、自作スキルを再利用可能な形で配布したい場合はプラグインが推奨されています。目的によって使い分けてください。

外部から取り込む場合は、中身を確認してから使ってください。スキルの内容はAIの動作に影響するため、意図しない指示が含まれていないかの確認が必要です。

AIエージェントの業務活用について、導入の進め方と支援内容をまとめた資料をご用意しています。 社内での検討材料としてご活用ください。 ▶ 資料請求はこちら

実務で使われている代表的なスキル

どんなものを作ればよいかは、既存の例を見ると掴みやすくなります。ここでは公式や実務で使われている類型を4つ紹介します。

変更後の検証を自動化する

コードや設定を変更した後に必ず行う確認を、1つのスキルにまとめる使い方です。整形、静的解析、型チェック、テストの実行を順番に走らせます。

OpenAI自身の事例でも、コードや動作が変わったときに必要な検証一式を実行するスキルが使われていると報告されています。確認漏れが減り、レビューに回る前の品質が安定します。

手順自体は既にあるはずなので、書き出す作業は難しくありません。README やチーム内の口伝になっている確認事項を、そのまま形式に落とし込めます。

文書と実装のずれを検出する

ドキュメントが実装に追いついていない状態は、どの現場でも起きます。実装とドキュメントを突き合わせ、抜けや誤り、古い記述を洗い出すスキルが有効です。

人が定期的に行うには負担が大きい作業ほど、自動化の価値が出ます。リリース前や四半期ごとに実行する運用にしておくと、劣化を防げます。

この類型は開発以外にも応用できます。社内規程と実際の運用のずれを確認する、マニュアルと現行のシステム画面を突き合わせるといった使い方が考えられます。

レビューの観点を固定する

レビューで見るべき項目をスキルに書いておくと、誰が確認しても同じ観点で見られるようになります。人によって指摘の粒度が違うという問題への対処です。

書くべきは、確認する項目、判断の基準、指摘の書き方の3点です。とくに基準を明示しておくと、指摘するかどうかの判断がぶれにくくなります。

新しく参加したメンバーの立ち上がりも速くなります。暗黙の了解になっていた基準が文書として残るため、教える側の負担も減ります。

社内の書式に沿って文書を作る

開発以外でも使えるのがこの類型です。報告書、議事録、提案書など、社内で形式が決まっている文書の作成手順をスキルにします。

テンプレートをassetsに置き、参照する資料をreferencesに入れておけば、形式と内容の両方を揃えられます。毎回のトーンや構成のばらつきがなくなります。

この用途では、スクリプトは不要な場合がほとんどです。指示とテンプレートだけで完結するため、技術的な知識がない担当者でも作成できます。

配置場所とスコープ設計

チームで使う場合、どこに置くかが設計の中心になります。ここを理解していないと、共有したつもりが個人の環境にしか反映されていないという事態が起きます。

6つの読み込み場所

公式ドキュメントでは、スキルの読み込み場所が4つのスコープに整理されています。リポジトリ、ユーザー、管理者、そしてシステムです。

リポジトリのスコープはさらに3つに分かれます。現在の作業ディレクトリ、その上位のフォルダ、そしてリポジトリのルートです。Codexは作業ディレクトリからルートまでを遡ってスキャンする仕組みになっています。

この階層構造により、適用範囲を細かく制御できます。特定のモジュールだけに使うもの、リポジトリ全体で使うものを、置き場所によって分けられる設計です。

リポジトリ単位で共有する

チームで共有する際の基本は、リポジトリ内にスキルを置いてコミットすることです。全員が同じ内容を参照でき、変更履歴も残ります。

ルートに置けば、そのリポジトリを扱う全員が使えます。サブフォルダに置けば、その領域を担当するメンバーだけが使うという分け方も可能です。マイクロサービスごとに異なる規約がある場合に有効な使い方です。

レビューの対象にもなるため、内容の質が担保されやすくなります。個人の環境にだけ置いてある状態と比べ、誤りに気づく機会が増える点も利点です。

個人用と管理者用

リポジトリを問わず使いたいものは、ユーザーのスコープに置きます。個人の作業効率を上げるためのスキルはここが適しています。

組織として全員に配りたいものは、管理者のスコープを使います。マシンやコンテナ共通の場所に置くことで、そのマシンを使う全員に既定として提供できます。

システムのスコープには、Codexに最初から同梱されているものが含まれます。作成支援の機能などがここに該当し、追加設定なしで使える状態になっています。

同名のスキルは統合されない

注意が必要なのが、名前が重複した場合の挙動です。公式によると、同じ名前のスキルが複数あってもマージはされず、両方が一覧に表示されます。

つまり、個人用とリポジトリ用に同じ名前で別内容のスキルを置くと、どちらが使われるか分かりにくい状態になります。意図しない側が呼ばれる原因になります。

対策としては、命名の規則をチームで決めておくことです。用途や適用範囲が分かる接頭辞を付けておくと、重複と混乱の両方を防げます。

使わないスキルを無効化する

不要になったスキルは、削除せずに無効化できます。設定ファイルに対象のパスと無効化の指定を書くことで、一時的に外せます。

先に述べた起動時の一覧には上限があるため、使わないスキルを外しておくことは実用上の意味があります。数が増えて発動精度が落ちてきたら、まず棚卸しを検討してください。

設定を変更した後は再起動が必要です。有効か無効かがすぐ反映されないと感じた場合は、この点を確認してみてください。

AGENTS.md・MCP・プラグインとの違い

混同されやすい機能がいくつかあります。役割が異なるため、使い分けを整理しておくと設計が明確になります。

AGENTS.mdとの違い

AGENTS.mdは、リポジトリに対して常に適用される指示を書くファイルです。セットアップのコマンド、テストの実行方法、コーディング規約といった、そのリポジトリの前提条件を記述します。

違いは、常に読まれるか必要なときだけ読まれるかです。AGENTS.mdは常時適用の前提条件、Skillsは特定の作業のときだけ読み込まれる手順書という役割分担になります。

すべてをAGENTS.mdに書くと、使わない情報まで毎回読み込むことになります。作業ごとに必要な内容はスキルへ切り出すほうが、全体の効率は上がります。

MCPとの違い

MCPは、AIと外部のツールやデータソースを接続するための規格です。データベース、課題管理システム、社内システムなどへのアクセス手段を提供します。

Skillsが手順を渡すものだとすれば、MCPは道具を渡すものです。役割が異なるため競合せず、むしろ組み合わせて使う関係にあります。

実際、スキルの設定ファイルには、必要なツールへの依存を宣言する項目が用意されています。特定のMCPサーバーを前提とするスキルであれば、そこに記述しておく設計です。

プラグインとの関係

プラグインは、スキルやコネクタをまとめて配布するための仕組みです。複数のスキル、外部サービスとの接続設定、表示用の素材を1つのパッケージにできます。

公式の整理では、スキルはワークフローそのものを設計する形式であり、他の人に配布したいときにプラグインとしてパッケージ化するという関係です。作る段階と配る段階で使い分けます。

社内の限られた範囲で使うならリポジトリに置くだけで足ります。部門を越えて配布したい、あるいは外部に公開したい段階になってから、プラグイン化を検討すれば十分です。

使い分けの整理

3つの関係を整理すると、判断しやすくなります。常に適用する前提条件はAGENTS.md、特定作業の手順はSkills、外部システムへの接続はMCPです。

そして、作った資産を他の人に届けたい段階でプラグインを使います。この整理ができていれば、何をどこに書くべきかで迷う場面が減ります。

導入初期は、この区別が曖昧なまま何でもAGENTS.mdに書いてしまいがちです。運用を始める前に、チームで役割分担を決めておくことをおすすめします。

どの業務をスキル化すべきか、チームでどう共有すべきかでお悩みの場合は、無料の個別相談をご利用ください。 ▶ 相談予約はこちら

業務ナレッジとして運用する

スキルは作って終わりではありません。組織の資産として機能させるには、運用の設計が必要になります。

何をスキル化すべきか

対象として適しているのは、繰り返し発生し、手順が決まっていて、品質のばらつきが問題になる作業です。逆に、毎回判断が変わる作業には向きません。

開発では、変更後の検証手順、リリース前の確認項目、レビューの観点、文書と実装の突き合わせといった作業が候補になります。開発以外でも、定型的な報告書の作成や、社内の書式に沿った文書作成が対象です。

選ぶ基準は、レビューで毎回同じ指摘をしているかどうかです。同じ注意を繰り返している項目があれば、それはスキルに書き出すべき内容といえます。

増やしすぎない設計

便利だからといって数を増やすと、先に説明した上限に当たります。起動時の一覧が圧迫され、説明文が短縮され、最終的には一部が省略されるという流れです。

対策は、1つのスキルを1つの仕事に絞りつつ、細かすぎる分割は避けるという設計です。似た作業を別々のスキルにするより、1つにまとめて分岐を書くほうが管理しやすくなります。

定期的な棚卸しも必要です。使われていないスキルを無効化するだけでも、発動精度は改善します。四半期に一度でも見直す運用を組み込んでおくと、劣化を防げます。

統制と安全性

スキルの内容はAIの動作に直接影響します。誰でも自由に追加できる状態は、統制上の問題になります。

とくに注意すべきは、認証情報や顧客名などをスキル内に直接書いてコミットしてしまうことです。環境変数で参照する規約を決め、レビューで確認する体制を整えてください。

外部から取り込んだスキルについても、中身の確認は欠かせません。実行するスクリプトが含まれる場合は、何をするコードかを読んでから導入する運用にしておくべきです。情報処理推進機構の調査では、AIに関するポリシーや社内ルールをどちらも定めていない企業が16.7％、適切な利用を管理する社内ルールの作成が難しいと回答した企業が39.7％にのぼりました。

更新と陳腐化への対応

業務の手順が変われば、スキルも古くなります。更新されないまま残ったスキルは、誤った手順を再現し続けることになります。

運用で見えた改善点を反映する担当と、定期的に見直す頻度を決めておいてください。書きっぱなしにすると、かえって品質を下げる原因になります。

ネクストスケールでは、AIエージェントの業務活用に関する情報をコラムでも継続して発信しています。導入の検討材料としてあわせてご覧ください。

まとめ

Codex Skillsは、作業の手順と資料を1つのフォルダにまとめ、必要な場面でAIが自動的に読み込んで実行する仕組みです。オープンな標準規格として公開されており、複数のエージェントが同じ形式を採用しています。

作成に必要なのはSKILL.mdというファイル1つで、名前と説明文が必須です。説明文が暗黙的な呼び出しの判断に使われるため、適用範囲と境界を明確に書くことが精度に直結します。

見落とされやすいのが、起動時に読み込む一覧の上限です。モデルのコンテキストの最大2％、または8,000文字までとされており、数が多いと説明が短縮され、一部は省略されます。作りすぎると発動しなくなる点は設計時に考慮してください。

チームで使う場合は、リポジトリ内に置いてコミットするのが基本です。まずはレビューで毎回同じ指摘をしている項目を1つ選び、スキルとして書き出すところから始めることをおすすめします。

どの業務をスキル化すべきか、チームでどう共有すべきかでお悩みの場合は、無料の個別相談をご利用ください。 ▶ 相談予約はこちら