Codex Skills徹底解説：SKILL.mdとは何か、使い方は？（2026年版）

- 以下の事実や数値は、執筆時点（2026年8月）の公式ドキュメントと照らし合わせて確認しています。Codex SkillsやPluginsの用語は変化が速いため、依存する前に最新のドキュメントを確認してください。

Codex Skillsとは？

Codexのスキルとは、指示（および任意でスクリプト、参照資料、アセット）をひとつにまとめ、タスクが求めるときにだけCodexが取り込む、再利用可能な機能のことです。「データベースのマイグレーションはこうやる」とセッションのたびに説明し直す代わりに、一度SKILL.mdファイルとして書いておけば、Codexが必要に応じて読み込みます。

まず整理しておきたい区別があります。Codex SkillsはOpenAIがゼロから発明した形式ではありません。SKILL.mdはオープンなAgent Skills標準であり、標準自身のサイトによれば「もともとAnthropicが開発し、オープン標準として公開され、増え続けるエージェント製品で採用されている」ものです。AnthropicがまずClaude Code向けに提供し（2025年10月）、OpenAIは数週間のうちに同じファイル形式をCodexとChatGPTに採用しました。同じSKILL.mdが、2つのエコシステムで使われているのです。

実務的に言えば、スキルとは、名前と、トリガーとなるdescription（常にCodexから見える）、そしてMarkdown本文（一致したときにのみ読み込まれる）のことです。繰り返し行う、タスク型の作業のために作られています。たとえばlint修正の手順、マイグレーションのチェックリスト、changelogの書式などで、一般知識や常時読み込むプロジェクト文脈のためではありません。それはAGENTS.mdの役割で、後ほど取り上げます。

書く前に役立つ判断基準があります。これをセッションに何度も貼り付けることになりそうか、そして毎回ほぼ同じ内容のままか、ということです。答えがイエスなら、それはスキル向きです。触れているファイルや機能によって手順が変わる場合、あるいは単に「このリポジトリの仕組み」という一般知識である場合は、たいていほかの場所——ドキュメント、コメント、あるいはAGENTS.md——に属します。

SKILL.mdファイルの構造

スキルはスラッグにちなんで名付けられたフォルダで、必須ファイルが1つと、最大4つの任意ファイルで構成されます。

my-skill/
├── SKILL.md            (required)
├── scripts/            (optional - executable code)
├── references/         (optional - docs the skill can point to)
├── assets/             (optional - templates, static files)
└── agents/openai.yaml  (optional - Codex-specific UI + MCP metadata)

SKILL.mdそのものは、YAMLフロントマターに続いてMarkdownの指示が書かれています。必須のフィールドは2つだけです。

---
name: changelog-writer
description: Turn a git diff into a changelog entry. Use when the
  user asks for a changelog, release notes, or "what changed".
---

# Changelog writer

1. Run `git diff --stat` and `git log -5 --oneline`.
2. Group changes by type: Added, Changed, Fixed.
3. Write 3-6 bullet points in the project's changelog format.

nameは識別子で、descriptionはトリガーです。スキルが該当するかどうかをCodexが判断するために読む一行なので、あいまいに（「changelogに役立つ」）ではなく、正確に（「〜のときに使う」）書きましょう。

任意のagents/openai.yamlはCodex固有のものです。Claude Codeやほかのクライアントには影響せず、Codex/ChatGPTの中でスキルがどう見え、どう振る舞うかだけに関わります。現行のドキュメントによると、3つのグループのフィールドを扱います。インターフェース（display_name、short_description、icon_small/icon_large、brand_color、default_prompt）、ポリシー（allow_implicit_invocation、デフォルトはtrue）、そしてツール依存関係の一覧（スキルが必要とするMCPサーバーと、そのトランスポートおよびURL）です。このファイルのフィールド名は製品とともに変わるため、本番で頼る前に最新のドキュメントを確認してください。

Codex Skillsの仕組み（プログレッシブ・ディスクロージャー）

スキルを気軽に置いておけるようにする仕組みはプログレッシブ・ディスクロージャー（段階的開示）と呼ばれ、公式ドキュメントによると3つの段階で動作します。

1. 発見（Discovery） - 起動時、Codexは各スキルのnameとdescriptionだけを読み込みます。スキルが存在することを知るには十分でも、まだ使うには足りません。
2. 起動（Activation） - プロンプトがスキルのdescriptionに一致すると、CodexはSKILL.mdの本文全体をコンテキストに読み込みます。
3. 実行（Execution） - Codexは指示に従い、必要に応じてバンドルされたスクリプトを実行したり、references/assetsのファイルを取り込んだりします。

発見の段階には厳格な上限があります。最初のスキル一覧（インストール済みのすべてのスキルのnameとdescriptionを合わせたもの）は、モデルのコンテキストウィンドウの2%、あるいはコンテキストウィンドウのサイズが不明な場合は8,000文字——該当する方——に制限されます。これは競合があまり触れない実在の上限です。冗長なスキルを入れすぎると、一覧に載らないものが出てきます。

ここから2つの実務的な帰結が生まれます。第一に、descriptionは簡潔に書きましょう。ほかのスキルの余地が残りますし、あいまいなもの（「コードに役立つ」）は確実には発火しない一方で、正確なもの（「ユーザーがchangelogを求めたときに使う…」）は発火します。第二に、時間に依存する情報をdescriptionだけに置かないことです。スキルが動き出してから初めて意味を持つ内容なら、トリガー行ではなく本文に入れましょう。

Codexがスキルを探す場所（スコープと優先順位）

Codexは、最も具体的なものから最も一般的なものへと、複数の場所をスキャンしてスキルを探します。同じ名前が一致した場合は、より具体的な場所が優先されます。

Codexがスキルを認識できるようになったら、発動させる方法は2つあります。

• 明示的（Explicit） - Codex CLIやIDEで$skill-nameと入力（一覧を見るには/skills）、ChatGPTでは@skill-nameと入力します。
• 暗黙的（Implicit） - タスクをふつうの言葉で説明するだけです。Codexがそれを、見えているすべてのスキルのdescriptionと照合し、自動的に呼び出します。

リポジトリ単位のスキルは.agents/skills/にコミットしてチーム全員に行き渡らせ、個人的な習慣はユーザースコープのフォルダに置いて、プロジェクトをまたいで付いてくるようにしましょう。

Codexスキルのインストールと作成の方法

方法は2つあります。誰かが書いたものをインストールするか、自分で作るかです。

既存のスキルをインストールする

Codexのセッション内で、組み込みのインストーラースキルを実行します。

$skill-installer linear

現在のカタログにある名前か、GitHubのURLを指定すると、スキルがあなたのスキルフォルダにクローンされます（デフォルトはユーザースコープ。リポジトリスコープにしたい場合はプロジェクトのパスを渡します）。知っておくと役立つ最新事情がひとつあります。OpenAIのスキルカタログはすでに一度移動しています。GitHubのopenai/skillsには非推奨のバナーが付き、openai/pluginsを指しています——そして本稿執筆時点で、その後継リポジトリ自体もアーカイブされています（読み取り専用で、代替は示されていません）。今のところ、どちらのGitHubリポジトリも信頼できる最新のカタログではありません。公式ドキュメントのページを、信頼に足る唯一のリンクとして扱い、$skill-installerのデフォルトのソース一覧は変わり続けると考えてください。スクリプトの中で実行する前に、実際に何を解決するのかを確認しましょう。

対話型クリエイターで自分で作る

$skill-creator

これは、スキルの命名、トリガーとなるdescriptionの記述、本文の下書きを対話的に案内し、フォルダをあなたのスキルパスに保存します。自分で再利用するスキルなら、ツールそのものよりも3つの習慣が大切です。

1. descriptionは要約ではなくトリガーのように書きましょう——「Xのときに使う」は「Xに役立つ」に勝ります。
2. 本文はタスク型に保ちましょう。ひとつの具体的な仕事ではなく、常に真であるプロジェクト文脈を書いているなら、それはスキルではなくAGENTS.mdに属します。
3. 両方の呼び出し経路をテストしましょう——まず$your-skillで明示的に呼んで本文が動くことを確認し、次に自然な言葉で暗黙的に発動させて、descriptionが実際に発火することを確認します。

フォルダとファイルを手作業で作ることもできます——mkdir -p .agents/skills/my-skill && touch .agents/skills/my-skill/SKILL.md——対話型クリエイターは便利さのためのもので、必須ではありません。

Codex Skills対AGENTS.md対Plugins——どれが必要？

3つのプリミティブ、3つの役割。互いに競合してはいません——実際のCodexの構成のほとんどは、2つ、あるいは3つすべてを同時に使います。

公式の言い回しをほぼそのまま引くと、スキルは「特定のタスクやワークフローのための指示と補助リソースをまとめる」もので、プラグインは「スキルやコネクタ、あるいはその両方を含められる、インストール可能なバンドル」です。つまりプラグインはスキルと競合する4つ目の形式ではなく、ひとつまたは複数のスキルをまとめ、さらにコネクタのようなスキル以外のものも同梱できる、パッケージングの層なのです。

AGENTS.mdはまったく別の枠にあります。オンデマンドで読み込まれるのではなく、常にコンテキストにあります——だからこそ、そのアドバイスはスキルとは正反対になります。短く保ちましょう（コマンド、厳格なルール、重要なパス）、長くではありません。すべての行が、毎ターンごとにトークンを消費するからです。無駄のないものを書くための詳しい解説はAGENTS.md対CLAUDE.md対SKILL.mdを、Codex独自のAGENTS.md探索順序についてはCodex AGENTS.mdガイドをご覧ください。

実際には、3つは積み重なるもので、互いの代わりにはなりません。典型的なリポジトリでは、ビルド/テストのコマンドや厳格なルールのために短いAGENTS.mdを置き、リリースノートや特定のリファクタリングのパターンのような繰り返しの仕事のためにいくつかのスキルを持ち、関連する複数のスキルとコネクタを一度に出荷するプラグインのバンドルを1つインストールする、という具合かもしれません。3つのどれもほかの代わりにはならず、それぞれが、Codexがいつ何を知り、何をすべきかについて、別々の問いに答えるだけなのです。

Codex SkillsはClaude Code Skillsと同じ？

核心においては、はい——しかもそれには、雰囲気だけでなく、しっかりした一次情報があります。標準自身のサイトであるagentskills.ioは、「Claude Code」と「ChatGPT & Codex」の両方を、対応クライアントとして並べて挙げており、この形式は「もともとAnthropicが開発し、オープン標準として公開され、増え続けるエージェント製品で採用されてきた」と述べています。

ここは正確に言っておく価値があります。OpenAIのどのページも、「Claude Codeと互換性がある」とその言葉どおりには述べていません。相互互換という主張は、標準自身のクライアント一覧と、独立した第三者の記事に基づくもので、OpenAIの引用ではありません——だから本記事はこう位置づけます。同じオープン標準であって、OpenAIによるClaude Codeの公式な保証ではない、と。

2つのツールの間で実際に持ち運べるもの。それはSKILL.mdファイルそのもの——name、description、Markdown本文、そしてscripts//references/assetsのフォルダです。一方のツールでスキルを書けば、読み込まれない追加分も含めて、核となるファイルはもう一方でも機能します。

持ち運べないのは、各ツールのクライアント固有の追加分で、これはもう一方が単に無視します。

• Codexが加えるもの：ChatGPTデスクトップのUIメタデータとMCPツール依存関係のためのagents/openai.yaml。
• Claude Codeが加えるもの：context: fork（スキルを隔離されたサブエージェントで実行する）とdisable-model-invocation（副作用のあるスキルの自動発火を防ぐ）——詳しい内訳はClaude Code Skills解説をご覧ください。

実務的な要点：クライアント固有のフロントマターなしでスキルを作れば、デフォルトで移植可能です。Codex専用やClaude専用のフィールドを加えても、もう一方のツールはそれを無視するだけ——壊れることはなく、ただそこでは何もしないだけです。

自分で書きたくない？既製のスキル・ワークフローキット

正確で個人的なワークフローが欲しいときは、手作業でスキルを書くのもよいものです。空のSKILL.mdからではなく、厳選されたライブラリから始めたいなら、そこがAgentKitが正直に埋めるギャップです——Codexにどう組み込まれるかはCodexでAgentKitを使うで、あるいは直接agentkit.bestでご覧ください。名前が紛らわしいので手短に区別しておくと、これはアフィリエイトのAgentKit（agentkit.best、CLIはak）であって、OpenAI自身のAgentKit/Agent Builder製品ではありません。

境界をはっきりさせておきましょう。Codexのネイティブなスキル機能は無料で、ChatGPTプランに含まれています——ここに購入が必要なものは何もありません。AgentKitは別個の有料アドオンです。既製のスキル、サブエージェント、ワークフローを厳選したキットで、ak kit init engineer --target codex --globalでCodexにインストールし、各SKILL.mdを自分で手書きする代わりに$ak:cookで実行します。「誰かがすでに作ってテスト済み」という選択肢であって、スキルが機能するための必須要件ではありません。

FAQ

Codex Skillsは無料ですか？

はい。スキルはCodexのネイティブ機能で、ChatGPTプランに含まれています——自分のSKILL.mdファイルの作成、インストール、実行に追加費用はかかりません。費用が発生するのは、自分で作る代わりに第三者の既製キットを買うことを選んだ場合だけです。

CodexスキルとAGENTS.mdの違いは何ですか？

スキルはオンデマンドで、タスクがそのdescriptionに一致したときにのみ読み込まれます。AGENTS.mdは常時読み込みで、毎ターン、コンテキストに座っています。具体的で繰り返せる仕事にはスキルを、常に知っておくべきコマンドやルールにはAGENTS.mdを使いましょう。

Codex SkillsはClaude Codeで動きますか？

核となるSKILL.mdファイルは動きます——両方のツールがオープンなAgent Skills標準を読み、agentskills.ioは両方を対応クライアントとして挙げています。クライアント固有の追加分は行き来しません。Codexのagents/openai.yamlはClaude Codeに無視され、Claude Codeのcontext: fork / disable-model-invocationのフィールドはCodexに無視されます。

カスタムのCodexスキルはどこに置きますか？

リポジトリ全体なら：リポジトリのルートの.agents/skills/（チームにも行き渡るようコミットします）。個人用で、すべてのプロジェクトに適用するなら：$HOME/.agents/skills。Codexはさらに、現在の作業ディレクトリとその親、加えて管理者用およびシステム同梱の場所を、その順序で確認します。

ほかの人のスキルをインストールできますか？

はい——Codexの中から$skill-installerを実行し、カタログの名前かGitHubのURLを指定すると、スキルがあなたのスキルフォルダにクローンされます。第三者のスキルはインストールする前に、新しい依存関係をレビューするのと同じように、そのSKILL.mdとスクリプトを確認しましょう。

openai/skillsはまだ公式のスキルカタログですか？

いいえ。GitHubのopenai/skillsは非推奨で、openai/pluginsを指しています——そして本稿執筆時点で、openai/plugins自体もアーカイブされています（読み取り専用）。どちらのリポジトリも現役のカタログではありません。代わりに、learn.chatgpt.com/docs/build-skillsの公式ドキュメントを使ってください。

まとめ

Codexのスキルとは、フォルダと、SKILL.mdファイルと、トリガーとなるdescription——それ以上に風変わりなものではありません。AGENTS.mdが常時オンなのに対してこれはオンデマンドで、両方が同じオープンなAgent Skills標準を読むためClaude Codeに移植でき、Codex自体に同梱されているため無料です。小さく始めましょう。Codexに何度も説明し直しているタスクをひとつ選び、簡潔なdescriptionを書き、プログレッシブ・ディスクロージャーにコストを抑えてもらうのです。ライブラリを一から書きたくないなら、AgentKitのような厳選キットが有料の近道です——必須ではありません。AGENTS.mdがスキルとどう並び立つかはCodex AGENTS.mdガイドで、まだ全体像をつかんでいる途中ならCodexとは何かからご覧ください。