Codexのスキル（Skills）は、フォルダーを1つ作り、その中にnameとdescriptionを書いたSKILL.mdを置くと作れます。
リポジトリの中で使うなら .agents/skills、どのリポジトリでも使うなら $HOME/.agents/skills の下に置きます。
Codex CLI・IDE拡張では、入力欄で $ に続けてスキル名を書くか、説明文から自動で選ぶのに任せます。
ChatGPT Workでは @ でスキルを選びます。
この記事は、2026年10月18日に開いたOpenAIの公式ドキュメント「Agent Skills」（developers.openai.com/codex/skills）と、そこからリンクされているAgent Skillsの仕様をもとにしています。
この記事の作成例について、作成・呼び出し・自動選択を実機で一通り再現した検証は含みません。
Codexは更新が速く、仕様や数字が変わることがあるので、作る前に公式ドキュメントも確認してください。
スキルのしくみ
公式ドキュメントでは、スキルは指示・資料・必要に応じたスクリプトをひとまとめにして、決まった作業の手順をCodexに伝え、繰り返し使いやすくするものと説明されています。
Codexは最初に、各スキルの名前と説明（とファイルの場所）だけを読み込み、使うと決めたスキルについてだけSKILL.mdの本文を読みます。
この最初の一覧は、既定ではモデルのコンテキストの2%まで、コンテキストの大きさが分からない場合は8,000文字までに収められます（2026年10月18日時点の記載）。
スキルが多いと説明文から先に短くされ、さらに多いと一部のスキルが一覧から外れて警告が出ると書かれています。
この上限は config.toml の skills.max_context_tokens で、10,000トークンまで変えられます。
対象は最初に渡すスキル一覧の容量であり、選ばれたSKILL.mdの本文をこの上限で切り詰める設定ではありません。
フォルダーの構成
| ファイル・フォルダー | 役割 |
|---|---|
| SKILL.md | 必須。nameとdescriptionの見出し情報と、Codexに守らせる指示 |
| scripts/ | 任意。実行するコード |
| references/ | 任意。参照させる資料 |
| assets/ | 任意。ひな形や素材 |
| agents/openai.yaml | 任意。表示名・アイコン・自動呼び出しの可否・必要なツールの指定 |
公式のベストプラクティスでは、決まった結果が必要な場合や外部のツールが要る場合を除き、スクリプトより指示で書くことが勧められています。
SKILL.mdの書き方
SKILL.mdは、先頭の --- の行で囲んだ部分にnameとdescriptionを書き、その下にCodexへの指示をMarkdownで書きます。
次は、変更点のメモから更新履歴の下書きを作るスキルの例です。
---
name: changelog-draft
description: 直近のコミットから、利用者向けの更新履歴の下書きを作る。リリース前に「更新履歴」「リリースノート」「変更点のまとめ」を頼まれたときに使う。コードの修正やコミットの作成には使わない。
---
# 更新履歴の下書きを作る
1. 対象リポジトリと比較元のタグ・コミットを確認する。指定がなく一意に決められない場合は利用者に確認する
2. git log で、比較元から現在の対象コミットまでの変更を一覧にする
3. 利用者に関係する変更だけを選び、「追加」「変更」「修正」に分ける
4. 1項目1行で、利用者から見た変化を書く
5. CHANGELOG.md は書き換えず、下書きを返答に出すフォルダーは changelog-draft という名前にし、この中にSKILL.mdを置きます。
nameの決まり
Agent Skillsの仕様では、nameは次の決まりに合わせます。
- 1〜64文字
- 小文字の英字・数字・ハイフンだけ（大文字は使えない）
- ハイフンで始めたり終えたりしない
- ハイフンを2つ続けない
- 親のフォルダーの名前と同じにする
descriptionの書き方
descriptionは、Codexが依頼に合うスキルを選ぶための重要な手掛かりです。
記載するだけで毎回の選択や指示の遵守が保証されるわけではないため、後述の呼び出しテストも行います。
公式ドキュメントでは、使う場面と使わない場面の境目をはっきり書き、主な用途ときっかけになる言葉を先頭に置くよう勧められています。
スキルが多くて説明文が短くされても、先頭の言葉で選ばれるようにするためです。
仕様では、descriptionは1〜1,024文字で、何をするスキルか、いつ使うかの両方を書くとされています。
置き場所と効く範囲
Codexは、リポジトリ・ユーザー・管理者・システムの4種類の場所からスキルを読み込みます。
| 種類 | 置き場所（公式の表記） | 向いている使い方 |
|---|---|---|
| リポジトリ | $CWD/.agents/skills | Codexを起動したフォルダーの作業だけで使うスキル |
| リポジトリ | $CWD/../.agents/skills | Gitリポジトリの中の、上の階層で共有するスキル |
| リポジトリ | $REPO_ROOT/.agents/skills | リポジトリ全体で、どのサブフォルダーからでも使うスキル |
| ユーザー | $HOME/.agents/skills | 自分がどのリポジトリでも使うスキル |
| 管理者 | /etc/codex/skills | マシンやコンテナーの全員に配るスキル |
| システム | Codexに同梱 | skill-creatorなど、OpenAIが用意したスキル |
リポジトリの中では、作業中のフォルダーからリポジトリの一番上まで、各階層の .agents/skills が読まれます。
同じ名前のスキルが2つあっても統合はされず、両方が選択肢に出ると書かれています。
シンボリックリンクにしたスキルのフォルダーも、リンク先をたどって読み込まれます。
Windowsでの具体的なフォルダーの位置は、公式ドキュメントには書かれていません。
スキルを作る3つの方法
| 方法 | 向いている場合 |
|---|---|
| $skill-creator を呼ぶ | やりたいことを言葉で説明して、ひな形を作ってもらう |
| フォルダーとSKILL.mdを手で作る | 書く内容が決まっている |
| Record & Replay で操作を記録する | 説明するより見せたほうが早い作業 |
公式ドキュメントによると、$skill-creator は、スキルが何をするか、いつ呼ばれるべきか、指示だけにするかスクリプトも含めるかを尋ねてきます。
何も選ばなければ、指示だけのスキルになります。
スキルを呼び出す
- 明示して呼ぶ：Codex CLIやIDE拡張では、/skills を実行するか、入力欄に $ を打ってスキルを選ぶ
- 自動で呼ばれる：依頼の内容がdescriptionに合えば、Codexがスキルを選んで使う
自動で呼ばれたくないスキルは、agents/openai.yaml の policy で allow_implicit_invocation を false にします。
この場合も、$ で名前を指定すれば使えます。
policy:
allow_implicit_invocation: false動作を確かめる
- /skills を実行するか $ を打ち、作ったスキルが一覧に出るかを見る
- $changelog-draft のように名前を指定して呼び、指示どおりに動くかを確かめる
- 名前を指定せずに、descriptionに書いた場面の依頼を出し、自動で選ばれるかを見る
- descriptionに書いた「使わない場面」の依頼も出し、選ばれないことを確かめる
公式のベストプラクティスにも、descriptionに対して依頼文を試し、意図どおりに呼ばれるかを確かめるよう書かれています。
Codexはスキルの変更を自動で検知しますが、変更が反映されないときはCodexを再起動するよう案内されています。
スキルが出てこないときの確認点
| 確かめること | 直し方 |
|---|---|
| SKILL.mdにnameとdescriptionがあるか | 先頭の区切り線の間に、2つとも書く |
| nameがフォルダー名と同じか | どちらかに合わせる（小文字・数字・ハイフンだけ） |
| 置き場所が上の表のどれかか | Codexを起動したフォルダーから見て、読まれる場所に置く |
| スキルが多すぎないか | 一覧から外れた警告が出ていれば、不要なスキルを無効にするか skills.max_context_tokens を見直す |
| 変更が反映されていない | Codexを再起動する |
スキルを消さずに止める
使わないスキルは、~/.codex/config.toml に次のように書くと、消さずに無効にできます。
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = falsepath には、止めたいスキルのSKILL.mdの場所を書きます。
config.toml を変えたあとは、Codexの再起動が必要です。
ほかの人に配る・人のスキルを入れる
公式ドキュメントでは、フォルダーに置くスキルは手元での作成やリポジトリ単位の作業向けで、ほかの人に配るならプラグインにまとめるよう勧められています。
プラグインには、複数のスキルや、MCPサーバーへの接続設定も一緒に入れられます。
単独のスキルはChatGPTデスクトップアプリ・Codex CLI・IDE拡張で利用できます。
WebやモバイルのChatGPTのChat・Workでも使える形で配る場合は、スキルをプラグインに含めます。
ローカルのフォルダーに置くだけで、Web版やモバイル版へ自動的に配布されるわけではありません。
OpenAIが選んだスキルを手元に入れるときは、$skill-installer を使います（例：$skill-installer linear）。
関連する記事
- Codexデスクトップアプリのコマンドと、スキルでの自作の概要：Codexデスクトップアプリのコマンド一覧
- Claude Codeで同じことをする場合：Claude CodeのSkillsとスラッシュコマンドの作り方
- Codexの入れ方と config.toml：Codex CLIのインストール方法
参考にした資料
初回確認は2026年10月18日です。
10月23日に再照合し、OpenAIのリンク先が「Build skills」に移動していることも確認しました。
呼び出し表記はCodex CLI・IDE拡張とChatGPT Workで区別してください。
