CodexについにSkillsが来たので徹底解説
CodexについにSkillsが来たので徹底解説
先日のアップデートでようやくCodexにも待望のSkillsが実装された。この機能を待ち望んでいた方も多いのではないだろうか。今回はこのSkillsをまだ活用していない方に向けて仕組みと利用例を徹底解説している。ぜひ参考にしていただけたら嬉しい。
ちなみにSkillsはCodex特有の仕組みではなく、もともとClaude Codeで実装されていた概念で、エージェントが動的に発見・ロードできる、指示・スクリプト・リソースのパッケージだ。「ナレッジの目次だけ最初にLLMに渡して、本当に必要な時だけ中身を読み込む」仕組み。コンテキストエンジニアリングの一環として位置づけられる。
一言で言うと
個人的な解釈だと、Skillsは必要な時にLLMの判断で自動的に読み込まれるカスタムコマンドに近い。
ただ、その説明だけでは「で、それの何が便利なの？」という感想になるだろう。ここからは詳しく仕組みを見ていこう。
Skillsの仕組み
2段構造
Skills自体はYAMLフロントマターと本文の2段構造になっている。
---
name: skill-name
description: このスキルの説明（いつ使うか、何をするか）
---
# 本文
ここに実際の指示を書く
~/.codex/skills/*/SKILL.md という形式で配置すると、nameをスキル名として認識、descriptionをそのスキルについての説明として認識してくれるようになる。
descriptionが肝
この説明が重要で、どういうタイミングで使うか、どういう用途なのかを詳しく書いておく。公式ドキュメントによると、nameは100文字以下、descriptionは500文字以下で定義せよとのこと。この辺りもコンテキスト効率化を意識した制限のように思う。
ここに書いた名前と説明が、目次としてLLMに最初に渡される。会話のやり取りの中で、「この目次に書いてある要素を利用したい」とLLMが判断した時に、初めて内容のプロンプトが呼び出される仕組みだ。
目次だけ渡して、必要な時に本文を読む
Skillsは段階的開示と呼ばれる設計思想に基づいて作られている。
起動時、Codexは全Skillsのnameとdescriptionだけをコンテキストに含める。本文は含めない。会話の中で「このSkillが使えそうだ」とLLMが判断した時点で、初めて本文が読み込まれる。
必要な時に必要な分だけコンテキストを使う。まさにコンテキストエンジニアの基本を実践するための手法となっている。
内部的にはAGENTS.mdの延長
ちなみにSkillsは内部的にはAGENTS.mdの後ろにnameとdescriptionを箇条書き形式で追加してLLMに渡しているようだ。
実際にAGENTS.mdファイルが書き換わるわけではないが、内部ではそういった仕組みとして成り立っている。
実例：error-analyzer
それでは、仕組みがわかったところで実装例を見ていこう。今回はエラーを分析・調査し、結果をドキュメントに出力するSkillを作成した。
SKILL.md全文を見る
---
name: error-analyzer
description: エラーや不具合の調査と日本語レポート作成（軽いヒアリング付き・ファイル自動生成）
---
あなたはこのリポジトリの不具合調査担当エンジニアです。
このコマンドは、個別のエラー／不具合について
- 必要最低限のヒアリング
- リポジトリやブランチ／PRの調査（読み取りのみ）
- 日本語での調査レポート作成（Markdown・新規ファイル作成）
を行うためのものです。
重要な制約:
- 実装や修正など、アプリケーションのソースコードや設定ファイルは一切変更しないこと。
- 編集してよいのは「不具合調査レポート用の Markdown ファイル」のみとし、それ以外のファイルには変更を加えないこと。
- 出力・コメント・ドキュメント本文はすべて日本語で書くこと。
---
## フェーズ1: ヒアリング（初回の応答）
初回の応答では、レポートを書き始めず、次の趣旨の質問だけを日本語で行ってください。
質問は「合計で 3 個以内」に抑え、短く簡潔に聞きます。
1. 不具合の種類
- 「今回の不具合は、新しく実装中の機能に関するものですか？それとも既存機能の不具合ですか？」
2. 分岐:
- 新規実装中の機能の場合:
- 「実装中のブランチ名と、どのブランチとの差分を見るべきか（ベースブランチ名）を教えてください。」
- 「関連する GitHub PR があれば、PR 番号または URL を教えてください。」
- 既存機能の場合:
- 「この不具合が発生している環境（ローカル／ステージング／本番など）を教えてください。」
- 「わかる範囲で構わないので、ざっくりした再現手順を教えてください。」
3. 期待する挙動
- 「本来どう動いてほしいか（期待する挙動）を一言で教えてください。」
補足:
- すでにユーザーが会話内に情報を書いている場合は、重複して聞かず、省略できる質問は省いてください。
- まだエラー内容やログが貼られていない場合は、
「エラーメッセージやログ、画面の挙動がわかる情報を貼ってください」
とだけ追加で依頼しても構いません（これも 3 個以内に収まるように調整すること）。
- このフェーズではレポートファイルの作成や編集は行わないこと。
---
## フェーズ2: 調査とレポート作成（情報が揃ったあとの応答）
ユーザーから必要な回答が得られたあと（または、会話に十分な情報があると判断できたあと）の応答では、
次の手順で調査とレポート作成を行います。
1. 会話ログに貼られたエラーメッセージやログ、不具合の説明を整理する。
2. ユーザーから指定された内容にもとづき、読み取り専用で調査する:
- 新規実装中の機能の場合:
- 指定された実装ブランチとベースブランチの差分を確認する。
- 関連 PR が指定されている場合は、その PR 内の変更点も確認する。
- 既存機能の場合:
- 不具合の発生箇所に関係しそうなコード・設定ファイルを読み取り専用で確認する。
3. 得られた情報から、原因の仮説と影響範囲を整理する。
gh コマンドなどが利用可能な環境であれば、PR や差分の取得に使って構いません。
利用できない場合は、その旨をレポート中に軽くコメントしてください。
---
## レポートファイルの作成ルール（自動生成）
レポートを書くファイルは、常に「AI 側で自動的に決めて新規作成」します。
- 保存先: リポジトリのカレントディレクトリ直下（`./`）
- ファイル名: 日付と短い日本語タイトルを含む Markdown ファイル名
- 形式の一例:
`2025-11-26_ログインエラー調査レポート.md`
- 日付は `YYYY-MM-DD` 形式。
- タイトル部分は「1. 問題の概要」で記載する内容を短く要約して使う。
- ファイルシステム上問題になりそうな記号は避け、必要に応じて `_` に置き換える。
ユーザーからチャット上で特別な指示がない限り、このルールを変更せずに毎回自動生成してください。
レポート本文を出力する前に、決定したファイル名について、次のような一文を先頭に出してください。
> この不具合調査レポートは `./YYYY-MM-DD_タイトル調査レポート.md` として新規作成します。
（ここで実際のファイル名を埋めてください）
---
## レポートの構成（Markdown・日本語）
レポートは決定したファイルに書き込むことを前提とし、次のセクションをこの順番で含めてください:
# 1. 問題の概要
- 一言でどんな問題か
- 発生環境・前提条件（わかる範囲で）
# 2. 発生している事象
- 実際に確認されたエラー内容・ログ・画面の挙動
- 再現手順（わかる範囲で箇条書き）
# 3. 調査内容と観察結果
- どのブランチ／PR／ファイルを確認したか
- そこで分かった事実を箇条書きで整理
- 特に、期待する挙動とのギャップがどこにあるか
# 4. 原因の仮説
- どの部分に問題がありそうか
- その根拠（コード上の挙動やログからの推測）
# 5. 影響範囲
- 影響を受けそうな機能・画面・ユーザー
- 既知の制約や、不明点・要確認事項
# 6. 今後の対応メモ（任意）
- 追加で行うべき調査
- 実装・修正を行う場合の方針案（あくまで方針のみ。具体的なコード変更案は書かない）
---
## 出力形式
調査フェーズ以降の応答では、次の 2 点だけを出力してください。
1. 先頭に、実際に新規作成するレポートファイル名を示す一文
（例: `この不具合調査レポートは \`./2025-11-26_ログインエラー調査レポート.md\` として新規作成します。`）
2. それに続けて、上記構成に従った日本語の Markdown レポート本文。
ソースコードや設定ファイルの変更提案は一切行わず、このレポート用ファイルの新規作成・更新だけを行ってください。
ファイルは~/.codex/skills/error-analyzer/SKILL.mdに置いている。
このSkillをCodexが認識すると、「エラーが起きた」「不具合を調べて」といった文脈でLLMが自動的に読み込んで、ヒアリング→調査→レポート作成という一連の流れを実行してくれる。
また、現状experimentalな機能ということもありconfig.tomlに以下の記述を足さないと有効化されないので注意。
[features]
skills = true
使ってみた
今回はあらかじめ簡単な構文エラーを発生させたプロジェクトで試した。
エラーをcodexが確認できた上で、調査せよと指示した結果がこちら。
ご覧の通り、明示的にSkillsを利用しろと指示してないが、エラー調査のためのSkillsがあることを認識し自分の判断で利用していることがわかるだろう。このように必要に応じて専用のプロンプトを読み込み、利用できる点が魅力だ。
残念なところ：プロジェクトスコープがない
声を大にして言いたいが、今のCodex CLIではプロジェクトごとにSkillsを定義できない。~/.codex/skills/ というグローバルなスコープ、つまりどのプロジェクトからも参照されるスコープにしか定義できない。
これは現状のカスタムコマンドと同じ制限で、改善を望む声が多いポイントだ。
正直かなり不便で、ここさえ改善されればCodexの使い勝手は相当上がると思っている。プロジェクト固有のSkillsを .codex/skills/ のような形で置けるようになれば、チームでの運用も一気に現実的になる。
MCPとは別物
SkillsとMCPを比較するような説明も見かけるが、自分の解釈としては別物だと考えている。
- MCP = 外部アクセス用のプロトコル
- Skills = あらかじめ用意されたプロンプトを、どう適切なタイミングで読み込むか、その運用をある程度仕組み化したもの
ただ、Skills内にはスクリプトも置いておける。複数のスクリプト（外部アクセスなどを適宜行うもの）とその使い方を1つのSkillにまとめ、さらにその要約をdescriptionに渡すことで、「必要な時だけコンテキストに含めるMCP」のような使い方もおそらく可能だ。使い方次第でコンテキスト管理をより効率化できるので、この辺りはアイデア次第で様々な活用法がありそうだ。
最初の一歩としておすすめしたい使い方
まずは、今までカスタムコマンド・スラッシュコマンドとして運用していたものの中で、「これ、状況に応じて自動的に読み込まれたらいいのに」と思っていたものをSkills化してみるといい。
あとは、必要な時だけ呼び出したいコーディングルールなど、AGENTS.mdにわざわざ置いておく必要がないと思うプロンプトを切り出してSkills化していくと効果を感じられるはずだ。
AGENTS.mdは常に読み込まれるからコンテキストを食う。必ず読んでほしい内容はAGENTS.mdに、「常に必要ではないが、特定の状況では欲しい」という知識はSkillsに切り出す、この使い分けがコンテキストエンジニアリングの基本になってくると考えている。
こちらもぜひ
Codexでサブエージェントを独自実装する手法を解説しているので、こちらもぜひ。
参考リンク
Codex CLI が Skills をサポート - laisoさんの記事を参考にしました
Codex公式 - Codex公式の説明を参考にしました
Anthropic公式
Discussion