CodexでSkillsを作る方法｜SKILL.mdの配置・呼び出し・動作確認

Codexのスキル（Skills）は、フォルダーを1つ作り、その中にnameとdescriptionを書いたSKILL.mdを置くと作れます。

リポジトリの中で使うなら .agents/skills、どのリポジトリでも使うなら $HOME/.agents/skills の下に置きます。

呼び出すときは、入力欄で $ に続けてスキルの名前を書くか、Codexが説明文から自動で選ぶのに任せます。

この記事は、2026年10月18日に開いたOpenAIの公式ドキュメント「Agent Skills」（developers.openai.com/codex/skills）と、そこからリンクされているAgent Skillsの仕様をもとにしています。

この機ではCodexを起動していないため、実機での再現は含まない内容です。

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への指示をMarkdownで書きます。

次は、変更点のメモから更新履歴の下書きを作るスキルの例です。

---
name: changelog-draft
description: 直近のコミットから、利用者向けの更新履歴の下書きを作る。リリース前に「更新履歴」「リリースノート」「変更点のまとめ」を頼まれたときに使う。コードの修正やコミットの作成には使わない。
---

# 更新履歴の下書きを作る

1. git log で、前回のタグ以降のコミットを一覧にする
2. 利用者に関係する変更だけを選び、「追加」「変更」「修正」に分ける
3. 1項目1行で、利用者から見た変化を書く
4. CHANGELOG.md は書き換えず、下書きを返答に出す

フォルダーは changelog-draft という名前にし、この中にSKILL.mdを置きます。

nameの決まり

Agent Skillsの仕様では、nameは次の決まりに合わせます。

• 1〜64文字
• 小文字の英字・数字・ハイフンだけ（大文字は使えない）
• ハイフンで始めたり終えたりしない
• ハイフンを2つ続けない
• 親のフォルダーの名前と同じにする

descriptionの書き方

Codexが自動でスキルを選ぶかどうかは、descriptionで決まります。

公式ドキュメントでは、使う場面と使わない場面の境目をはっきり書き、主な用途ときっかけになる言葉を先頭に置くよう勧められています。

スキルが多くて説明文が短くされても、先頭の言葉で選ばれるようにするためです。

仕様では、descriptionは1〜1,024文字で、何をするスキルか、いつ使うかの両方を書くとされています。

置き場所と効く範囲

Codexは、リポジトリ・ユーザー・管理者・システムの4種類の場所からスキルを読み込みます。

リポジトリの中では、作業中のフォルダーからリポジトリの一番上まで、各階層の .agents/skills が読まれます。

同じ名前のスキルが2つあっても統合はされず、両方が選択肢に出ると書かれています。

シンボリックリンクにしたスキルのフォルダーも、リンク先をたどって読み込まれます。

Windowsでの具体的なフォルダーの位置は、公式ドキュメントには書かれていません。

スキルを作る3つの方法

公式ドキュメントによると、$skill-creator は、スキルが何をするか、いつ呼ばれるべきか、指示だけにするかスクリプトも含めるかを尋ねてきます。

何も選ばなければ、指示だけのスキルになります。

スキルを呼び出す

• 明示して呼ぶ：Codex CLIやIDE拡張では、/skills を実行するか、入力欄に $ を打ってスキルを選ぶ
• 自動で呼ばれる：依頼の内容がdescriptionに合えば、Codexがスキルを選んで使う

自動で呼ばれたくないスキルは、agents/openai.yaml の policy で allow_implicit_invocation を false にします。

この場合も、$ で名前を指定すれば使えます。

policy:
  allow_implicit_invocation: false

動作を確かめる

1. /skills を実行するか $ を打ち、作ったスキルが一覧に出るかを見る
2. $changelog-draft のように名前を指定して呼び、指示どおりに動くかを確かめる
3. 名前を指定せずに、descriptionに書いた場面の依頼を出し、自動で選ばれるかを見る
4. descriptionに書いた「使わない場面」の依頼も出し、選ばれないことを確かめる

公式のベストプラクティスにも、descriptionに対して依頼文を試し、意図どおりに呼ばれるかを確かめるよう書かれています。

Codexはスキルの変更を自動で検知しますが、変更が反映されないときはCodexを再起動するよう案内されています。

スキルが出てこないときの確認点

スキルを消さずに止める

使わないスキルは、~/.codex/config.toml に次のように書くと、消さずに無効にできます。

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

path には、止めたいスキルのSKILL.mdの場所を書きます。

config.toml を変えたあとは、Codexの再起動が必要です。

ほかの人に配る・人のスキルを入れる

公式ドキュメントでは、フォルダーに置くスキルは手元での作成やリポジトリ単位の作業向けで、ほかの人に配るならプラグインにまとめるよう勧められています。

プラグインには、複数のスキルや、MCPサーバーへの接続設定も一緒に入れられます。

OpenAIが選んだスキルを手元に入れるときは、$skill-installer を使います（例：$skill-installer linear）。

関連する記事

• Codexデスクトップアプリのコマンドと、スキルでの自作の概要：Codexデスクトップアプリのコマンド一覧
• Claude Codeで同じことをする場合：Claude CodeのSkillsとスラッシュコマンドの作り方
• Codexの入れ方と config.toml：Codex CLIのインストール方法

参考にした資料

• OpenAI「Agent Skills」（Codexの公式ドキュメント）
• Agent Skills の仕様（Specification）

いずれも2026年10月18日に確認しました。