Codex Skillsの使い方｜SKILL.mdの書き方と段階的開示・AGENTS.mdの使い分け

Codex Skillsとは、特定タスク向けの手順・参考資料・任意のスクリプトをSKILL.md中心のフォルダにまとめ、Codexが明示呼び出しやタスク内容との一致に応じて読み込んで使える仕組み。

結論を先に置きます。Codex Skillsを使いこなす鍵は、SKILL.mdを「YAML設定欄＋本文」の2段で正しく書き、段階的開示でトークンを抑えつつ、常時適用のAGENTS.mdと役割を分けることにあります。この3点が噛み合うと、PRレビューやテスト作成のたびに長いプロンプトを打ち直す手間を減らせます。逆に言えば、設定欄の書き方が雑だとスキルは呼ばれず、本文に情報を詰め込みすぎるとコンテキストを圧迫する。つまずきやすいのはこの2点。本記事は、書き方そのものと、動かないときの確認手順までをまとめて扱います。

Codex Skillsとは何か

Codex Skillsは、特定のタスクに必要な手順や参考資料、任意のスクリプトをひとつのフォルダにまとめ、Codexが必要なときに読み込めるようにする仕組みです。モデルを追加学習させるのではなく、再利用できる作業手順をファイルとして提供するもので、毎回同じプロンプトを書き直す手間を減らせます。OpenAIのCodex公式ドキュメントで案内されている機能で、Anthropicが提唱した「Agent Skills」の規格に準拠しています。同じ規格をClaude CodeやGitHub Copilotも採用しているため、ツールをまたいでスキルを共有できる点も大きい。

個人の作業ノウハウやチームの開発フローを「動くドキュメント」として蓄積できる。これがSkillsの本質です。手順書をWikiに置いても結局は人が読んで実行しますが、SKILL.mdはCodex自身が読んで実行するため、手順の再現性を高めやすくなります。

何が解決されるのか

「PRレビューのときは命名規則とテストカバレッジを必ず見て、観点ごとにコメントを出して」——この種の指示を毎回プロンプトに書いていませんか。一度きりなら問題になりませんが、週に何度も繰り返すなら話は別。指示の表現が揺れれば出力も揺れますし、新しいメンバーが同じ品質を出すには口頭での共有が要ります。

Skillsはこの「指示の反復」を「資産化」に置き換えます。一度SKILL.mdに手順を固定すれば、以降はCodexがその手順を参照して動く。プロンプトを書き直す手間や品質のばらつきを抑えやすくなることが期待できます。蓄積したスキルはそのままチームの共有財産になります。

AGENTS.md・通常プロンプトとの位置の違い

Codexに指示を与える経路は大きく3つあります。その場で打つ通常プロンプト、リポジトリ全体に常時効くAGENTS.md、そして特定タスク時だけ呼ばれるSkills。役割の重心がそれぞれ違います。

通常プロンプトは一回限りの依頼。AGENTS.mdはプロジェクトの前提条件で、Codexが作業前に読み込みます（グローバルとプロジェクト階層のファイルを結合。空ファイルは無視され、既定で合計32KiBの上限があります）。Skillsは特定の作業手順で、タスクに合致したときだけ本文が読み込まれる。この振り分けを誤ると、常時読む必要のない手順がコンテキストを食い続けたり、逆に毎回必要な前提がスキル側に隠れて参照されなかったりします。詳しい使い分けは後半で表にまとめています。

SKILL.mdの書き方（YAML設定欄と本文の2段構造）

SKILL.mdは、冒頭の「YAML設定欄」と、その下の「本文」という2段構造になっています。設定欄はファイル先頭にハイフン3つの行で挟んで作り、その下に通常のMarkdownで手順を書く。Codexはまず各スキルのname・description・ファイルパスを初期一覧として読み込み、タスクに合うものを選んでから本文を取りに行きます。この順番が段階的開示の土台です。なお初期一覧はモデルのコンテキストの約2%（不明な場合は約8,000文字）が目安とされ、スキルが多いとdescriptionが短縮されたり一部が一覧から省略されたりすることがあります。

具体的なイメージを言葉で示します。先頭にハイフン3つの行を置き、次の行に name（スキルの識別名）、その下に description（どんなときに使うスキルか）を書く。さらにハイフン3つの行で設定欄を閉じ、その下に # PRレビュー手順 のような見出しと、番号付きの作業ステップを並べる。これがSKILL.mdの最小構成です。設定欄は数行、本文は手順の分だけ伸びる、という形になります。

YAML設定欄に書くこと（スキルの呼び出し条件）

設定欄の役割は、ずばり「呼び出し条件の宣言」です。暗黙呼び出しでは主にこの設定欄（とくにdescription）との照合でスキルが選ばれるため、設定欄が曖昧だと自動では呼ばれにくくなります（/skillsや$による明示呼び出しは別途可能です）。書く項目は主に2つ。識別名のnameと、用途を説明するdescriptionです。

nameは運用上、他スキルと重複しない短い識別名で、pr-reviewのように小文字英数字とハイフンにします（Agent Skills仕様では名前の長さや使える文字に制約があり、Codexでは同名スキルがマージされず両方表示され得ます）。重要なのはdescriptionのほう。ここが「いつこのスキルを使うか」をCodexに伝える唯一の手がかりになります。「GitHubのPRに対してレビュー観点でコメントを書く」のように、対象（PR）と行為（レビューコメント生成）を明示すると選ばれやすい。「便利なスキル」「いろいろ手伝う」のような漠然とした説明は避けてください。

本文に書くこと（実際の手順・参考資料）

本文には、選ばれたあとにCodexが実際になぞる手順を書きます。番号付きステップで、入力・判断基準・出力の形を順に示すのが基本。PRレビューなら「変更ファイルを一覧化する」「命名規則とテストカバレッジを確認する」「観点ごとにコメントを生成する」といった流れになります。

本文に長い背景説明や前提条件を盛り込みすぎないこと。本文はスキルが選ばれた後に丸ごと読み込まれるため、肥大化はそのままトークン消費につながります。判断に必要な手順だけを残し、共通の前提はAGENTS.md側へ寄せる。この切り分けが、後で効いてきます。

段階的開示の仕組みとコンテキスト節約

Codex Skillsは「段階的開示（progressive disclosure）」と呼ばれる方式で動きます。すべてのスキルの本文を最初から読み込むのではなく、まず設定欄だけをスキャンし、タスクに合致したスキルの本文だけを後から取りに行く。二段ロード、と言い換えると分かりやすいでしょう。

なぜこの方式が効くのか。スキルが10個、20個と増えても、設定欄は1スキルあたり数行に収まります。本文をすべて読み込む場合に比べ、初期一覧（name・description等）のスキャンだけなら必要なトークンを大きく抑えられます。実際に呼ばれた1〜2個の本文だけがコンテキストに乗るため、Codexは余計な情報を抱えずに済みます。

なぜ全文を毎回読まないのか

コンテキストには上限があります。すべてのスキル本文を常時抱えると、肝心のコードや会話の履歴を置く余地が削られていく。これは応答精度の低下に直結します。段階的開示は、この有限の容量を「いま必要な手順」に集中させるための割り切りです。

言い換えると、段階的開示は「索引を先に読み、本編は必要な章だけ開く」読書法に近い。索引（設定欄）が正確なら、必要な章（本文）に最短でたどり着けます。逆に索引の見出しが曖昧だと、欲しい章が見つからない。設定欄の質がそのまま呼び出し精度を左右する理由がここにあります。

呼び出されやすいSKILL.mdにする書き方

呼び出し精度を上げる勘所は、descriptionを「Codexが照合しやすい言葉」で書くことです。仕組み上、Codexはタスクの内容とdescriptionを照らし合わせてスキルを選びます。であれば、ユーザーが実際に依頼しそうな語をdescriptionに含めるのが理にかなっています。

たとえばPRレビュー用なら、「PR」「レビュー」「コメント」「変更点」といった、依頼時に出やすい語を説明文に織り込む。抽象的な美辞麗句より、対象と行為を名指しする具体語のほうが照合に効きます。1スキル1目的に絞るのも有効。「レビューもテスト生成も議事録整形も」と欲張ると、どのタスクにも中途半端に反応し、かえって精度が落ちます。

AGENTS.mdとの使い分け

AGENTS.mdとSkillsは、似て非なる役割を持ちます。AGENTS.mdはCodexが作業前に読み込む「前提条件」。Skillsは特定タスク時だけ読まれる「手順書」。この一文が使い分けの核心です。プロジェクト全体に効かせたいルールはAGENTS.md、特定の繰り返し作業の段取りはSkills、と覚えてください。

比較表（AGENTS.md vs Skills）

両者の違いを4つの軸で並べます。読み込みのタイミングとコンテキスト消費の違いに注目すると、どちらに何を書くべきかが見えてきます。

振り分けの判断基準

判断はシンプルな問いで分けられます。「それは毎回必要か、特定の作業のときだけ必要か」。インデント幅やコミットメッセージの規約のように、どの作業でも守ってほしいルールはAGENTS.md。PRレビューのときだけ参照する観点リストのように、特定タスクに紐づく段取りはSkills。

判断に迷ったら、コンテキスト消費で考えるのも手です。常時読み込まれるAGENTS.mdに手順を詰め込むと、関係ないタスクでもトークンを消費し続けます。逆に、毎回必要な前提をSkillsに隠すと、スキルが呼ばれない作業では参照されず、品質が安定しません。「常に効かせたいなら前提として上に、必要なときだけ呼びたいなら手順として下に」。この振り分けが運用の安定度を決めます。

最初の1スキルを作ってCodexに呼び出させる手順

仕組みが分かったら、最初の1スキルを動かしてみるのが近道です。ツール選定でも「数を増やすより、まず最も時間を奪っている1作業を見極める」という逆算の考え方がよく勧められます。スキル化も同じ。あれもこれもと作る前に、最も繰り返している1作業から始めます。

スキル化する作業の選び方

候補になりやすいのは、手順が決まっていて頻度が高い作業です。PRレビュー、テスト作成、議事録整形などが代表例。毎回ほぼ同じ指示を打っているなら、それは強いスキル化候補です。逆に、毎回ゴールが変わる探索的な作業はスキルに向きません。

選定の手順はこうです。第一に、直近1週間で「同じような指示を2回以上Codexに出した作業」を書き出す。第二に、その中で最も時間を奪っている1つを選ぶ。第三に、その作業の手順を3〜5ステップに分解する。最初から完璧を目指さず、動く最小のスキルを1つ仕上げることを優先してください。

作成から動作確認・定着の判断まで

公式には雛形を対話生成する$skill-creatorも用意されています。ここでは手動で作る場合の流れを示します。なおCodexはスキルの変更を自動検出しますが、反映されないときは再起動してください。

1. スキル用のフォルダを用意し、その中にSKILL.mdを作成する。Codexに読ませるには、リポジトリ用なら作業ディレクトリからリポジトリルートまでの.agents/skills/<skill-name>/SKILL.md、個人用なら$HOME/.agents/skills/<skill-name>/SKILL.mdに置く（更新が反映されないときはCodexを再起動）。
2. 先頭の設定欄にnameと、用途を明示したdescriptionを書く。
3. 設定欄の下に、選んだ作業の手順を番号付きで記述する。
4. Codexに、その作業に該当する依頼を出してスキルが呼ばれるか確認する。
5. 呼ばれない・出力が想定とずれる場合は、descriptionの語と本文の手順を調整する。

定着の判断には少し時間をかけます。新しく入れたツールは一定期間、実作業で試してから定着させるのが堅実です。スキルも同様で、1週間ほど実作業で使い、呼び出され方と出力の安定度を見てから手順を確定させるのが堅実です。1回の成功で完成と決めつけない。これが結果的に手戻りを減らします。

スキルが呼び出されない・動かないときの確認ポイント

「SKILL.mdを置いたのにCodexが使ってくれない」「想定と違う動きをする」。この種のつまずきは、原因の多くが3パターンに集約されます。症状から原因を切り分けると対処が早い。順に確認してください。

症状①: スキルが一向に呼び出されない

最も多いのが、descriptionが曖昧で照合に引っかからないケースです。Codexは設定欄のdescriptionとタスク内容を照らし合わせてスキルを選びます。説明が「便利なスキル」「作業を補助する」程度だと、どの依頼にも結びつかず素通りされる。

対処は、descriptionに対象と行為を具体的に書き直すこと。「コードを手伝う」ではなく「PRの変更点に対してレビュー観点でコメントを生成する」のように、依頼時に出る語を含めます。それでも呼ばれないなら、/skillsや$での明示呼び出しが効くか、agents/openai.yamlで暗黙呼び出し（allow_implicit_invocation）を無効にしていないか、nameが他スキルと紛らわしくないか、設定欄のハイフン3つの区切りが正しく閉じているかも確認してください。

症状②: 呼ばれるが出力が安定しない・重い

スキルは選ばれるのに、出力がぶれたり応答が重かったりする場合。原因は本文に情報を詰め込みすぎてコンテキストを圧迫していることが多い。背景説明や例外処理を延々と書くと、本文が肥大化して肝心の手順がぼやけます。

対処は、本文を「判断に必要な手順」だけに絞ること。冗長な前置きを削り、ステップを3〜5個に整理する。共通の前提条件は本文から抜き、AGENTS.md側へ移すと本文が軽くなります。1スキルが大きすぎるなら、目的ごとに分割するのも有効です。

症状③: 前提が無視される・毎回同じ指摘を繰り返す

「コミット規約を守ってほしいのに守られない」「毎タスクで同じ前提を伝え直している」。これは、本来AGENTS.mdに置くべき常時適用の前提を、Skills側に書いてしまっている典型です。スキルは該当タスクのときしか読まれないため、別の作業では前提が効きません。

対処は役割の置き直しです。プロジェクト全体に効かせたいルールはAGENTS.mdへ移す。特定作業の手順だけをSkillsに残す。前提と手順を物理的に分けると、どのタスクでも前提が効き、手順は必要なときだけ呼ばれる、という本来の姿に戻ります。

よくある質問（FAQ）

Q. Codex SkillsとClaude Code Skillsに互換性はありますか？

OpenAI・Anthropic両社の公式ドキュメントによれば、どちらもAnthropicが提唱した「Agent Skills」規格に準拠しています。SKILL.mdを「設定欄＋本文」で書く形式は共通で、ツールをまたいでスキルを共有できるとされています。ただしツール固有の有効化手順や対応項目は異なる場合があるため、移行時は各公式ドキュメントで確認してください。

Q. AGENTS.mdとSkillsはどちらを先に作るべきですか？

プロジェクト全体の前提が固まっていないなら、まずAGENTS.mdで共通ルールを定めるのが順当です。その上で、繰り返し発生する特定作業をSkillsに切り出します。前提（AGENTS.md）が土台、手順（Skills）が上に乗る、という関係。

Q. スキルは何個まで作れますか？

作成できるスキル数そのものの上限は公式に明示されていません。ただし起動時に読み込まれる初期一覧にはコンテキストの約2%（不明な場合は約8,000文字）という目安があり、スキルが多いとdescriptionが短縮されたり一部が一覧から省略されたりします。数を増やすほど初期一覧が圧迫される点に注意し、1スキル1目的で整理するのが無難です。

Q. 作ったスキルはチームで共有できますか？

共有できます。SKILL.mdはフォルダ単位のテキストファイルのため、リポジトリに含めてバージョン管理すれば、チームで同じ手順を再現できます。複数スキルの配布やアプリ連携・MCP設定までまとめたい場合は、Pluginとしてパッケージ化する方法もあります。ただし外部から入手したスキルは、SKILL.mdだけでなく同梱のスクリプトや参照先、外部通信を促す指示まで確認してから使ってください。信頼できないスキルは、機密情報の読み取りや外部送信、意図しないコマンド実行につながる可能性があります。とくにshell/bashの事前承認やMCP連携、取得元のバージョンを確認し、信頼できないスキルには実行権限を与えないでください。

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

2026年6月時点のOpenAI公式Pricingでは、Skillsごとの個別料金は掲載されていません。Codexの利用はChatGPT各プラン（Free・Go・Plus・Pro・Business・Enterprise & Edu）の利用枠・クレジット、またはAPI Key利用時のトークン課金に従うため、費用は公式Pricingと利用形態で確認してください。

まとめ

Codex Skillsを運用に乗せる要点は3つに整理できます。第一に、SKILL.mdは「YAML設定欄（name・description）＋本文（手順）」の2段構造で書く。第二に、段階的開示によって合致したスキルの本文だけが読み込まれるため、descriptionを具体語で書くほど正しく呼ばれ、本文は手順だけに絞るとトークンを節約できる。第三に、常時適用の前提はAGENTS.md、特定作業の手順はSkills、と役割を分ける。

呼ばれないときはdescriptionの具体性を、出力が重いときは本文の分量を、前提が効かないときはAGENTS.mdへの振り分けを見直す。この対応関係を押さえておけば、主要なトラブルは切り分けやすくなります。まずは最も繰り返している1作業を選び、最小のSKILL.mdを1つ動かすところから始めてください。仕様の具体項目は、下記の公式ドキュメントで裏取りしてから確定させるのが安全です。

参考資料

• OpenAI 公式: Codex Skills ドキュメント
• OpenAI 公式: AGENTS.md ガイド
• OpenAI 公式: Codex Pricing
• OpenAI Codex 公式 GitHub: openai/codex