先に結論
を一通り読んで、一番強く感じたのはこれです。
Codex Plugin は、単なる「追加機能」ではありません。
もっと正確には、
Skills・App integrations・MCP servers をまとめて、Codex にインストール可能な再利用ワークフローとして配布する仕組み
です。
公式ドキュメントでも、Plugins は Codex 向けに skills、app integrations、MCP servers を reusable workflows として bundle するものだと説明されています。Plugin には、特定作業の手順を渡す Skills、GitHub・Slack・Google Drive などに接続する Apps、追加ツールや共有情報にアクセスする MCP servers を含められます。(OpenAI Developers)
短く言うと、
Agent Skills は作業手順、MCP は外部接続、Codex Plugin はそれらを配布するパッケージ
だと思いました。
前回の Agent Skills が「AI に仕事のやり方を渡す仕組み」、MCP が「AI と外部システムをつなぐ標準」だとすると、Codex Plugin はその上にある「チームやプロジェクトに配る単位」です。
Codex Pluginとは何か
Codex Plugin は、Codex に追加できる再利用可能なワークフローのパッケージです。
たとえば、次のようなことができます。
- Gmail を読んで未読スレッドを要約する
- Google Drive、Docs、Sheets、Slides を横断して作業する
- Slack チャンネルを要約したり返信案を作る
- Codex Security plugin で許可されたコードをスキャンする
- Sites を使ってWebサイトやWebアプリを作成・デプロイする
公式ドキュメントでも、Plugin の例として Codex Security、Gmail、Google Drive、Slack、Sites が挙げられています。(OpenAI Developers)
ここで重要なのは、Plugin が「1つのツール」ではないことです。
Plugin は、複数の部品をまとめられます。
my-plugin/
├── .codex-plugin/
│ └── plugin.json
├── skills/
│ └── my-skill/
│ └── SKILL.md
├── hooks/
│ └── hooks.json
├── .app.json
├── .mcp.json
└── assets/
公式の Build plugins ドキュメントでも、すべての plugin は .codex-plugin/plugin.json を持ち、任意で skills/、hooks/、.app.json、.mcp.json、assets/ を含められると説明されています。(OpenAI Developers)
つまり Plugin は、AI エージェント向けの「配布可能な作業環境」に近いです。
なぜPluginが必要なのか
Agent Skills だけでも、かなり便利です。
たとえば、PRレビュー手順、リリースノート作成手順、障害報告のまとめ方などを Skill として書けます。
でも、実務ではそれだけでは足りないことがあります。
たとえば、PRレビューをするときに、
- GitHub のPRを読む
- 社内ドキュメントを参照する
- JiraやLinearのチケットを見る
- Slackの過去議論を確認する
- 最後にレビューコメントを書く
という流れがあるとします。
この場合、必要なのは「手順」だけではありません。
外部サービスへの接続も必要です。
場合によっては MCP server も必要です。
チームで配布する仕組みも必要です。
インストール時の説明やアイコンも必要です。
そこで Plugin です。
公式ドキュメントでも、まだ1つのリポジトリや個人ワークフローで試している段階なら local skill から始めるべきだが、チーム横断で共有したい、app integrations や MCP config をまとめたい、lifecycle hooks を含めたい、安定パッケージとして公開したい場合は plugin を作ると説明されています。(OpenAI Developers)
ここが本質です。
Plugin は、AI に能力を足すものというより、
AI に渡す作業環境を、他の人がインストールできる形にするもの
だと思います。
Pluginを構成する4つの部品
Codex Plugin を理解するには、次の4つを見ると分かりやすいです。
| 部品 | 役割 |
|---|---|
| Skills | 作業手順、判断基準、参照資料、補助スクリプト |
| Apps | GitHub、Slack、Google Drive など外部アプリとの接続 |
| MCP servers | 追加ツールや共有情報へのアクセス |
| Hooks | セッション開始時などのライフサイクル処理 |
公式ドキュメントでは、Plugin は Skills、Apps、MCP servers を含められると説明されています。また Build plugins では、lifecycle hooks も plugin に含められる構成要素として説明されています。(OpenAI Developers)
Skills
Skills は、Codex に特定タスクのやり方を教える部品です。
公式の Codex Skills ドキュメントでは、Skill は instructions、resources、optional scripts をパッケージ化して、Codex がワークフローを信頼性高く実行できるようにするものだと説明されています。また、Skills は reusable workflows の authoring format であり、Plugins は reusable skills and apps の installable distribution unit だと説明されています。(OpenAI Developers)
つまり、
Skill = ワークフローを書く単位
Plugin = ワークフローを配る単位
です。
Apps
Apps は、GitHub、Slack、Google Drive などの外部ツールに接続するための部品です。
Plugin が Apps を含む場合、Codex はセットアップ時または初回利用時に、ChatGPT 側でアプリのインストールやサインインを求めることがあります。公式ドキュメントでも、Plugin に apps が含まれる場合、Codex が setup 中または初回使用時に app のインストールやサインインを促すことがあると説明されています。(OpenAI Developers)
MCP servers
MCP servers は、Codex に追加のツールや共有情報へのアクセスを与える部品です。
Plugin は .mcp.json を含めることで MCP server 設定を bundle できます。公式ドキュメントでは、mcpServers が .mcp.json を指し、その中に direct server map または mcp_servers object を書けると説明されています。(OpenAI Developers)
つまり、MCP が「接続プロトコル」なら、Plugin はその MCP 設定を配布物に含める箱です。
Hooks
Hooks は、セッション開始時などの lifecycle event に応じて実行される処理です。
公式ドキュメントでは、Plugin が有効になっていると、Codex は user、project、managed hooks と並んで plugin の lifecycle hooks も読み込めると説明されています。ただし、plugin-bundled hooks は自動的に信頼されるわけではなく、ユーザーが現在の hook definition を確認して trust するまでスキップされると説明されています。(OpenAI Developers)
ここは大事です。
Hook は便利ですが、実行されるコマンドです。
だから、インストールしただけで無条件に信頼してはいけない。
この設計はかなり現実的だと思いました。
plugin.jsonはPluginの入口
Plugin の必須ファイルは .codex-plugin/plugin.json です。
最小構成なら、かなりシンプルです。
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
公式ドキュメントでも、最小の plugin は .codex-plugin/plugin.json を持ち、name、version、description、skills を含む例から始められると説明されています。(OpenAI Developers)
でも、公開やチーム配布を考えるなら、もっとリッチな manifest が必要になります。
たとえば、
{
"name": "my-plugin",
"version": "0.1.0",
"description": "Bundle reusable skills and app integrations.",
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"apps": "./.app.json",
"hooks": "./hooks/hooks.json",
"interface": {
"displayName": "My Plugin",
"shortDescription": "Reusable skills and apps",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"composerIcon": "./assets/icon.png",
"logo": "./assets/logo.png"
}
}
公式ドキュメントでは、manifest の役割は、Plugin を識別すること、skills・apps・MCP servers・hooks などの bundled components を指すこと、そして description・icons・legal links など install surface 向け metadata を提供することだと説明されています。(OpenAI Developers)
ここで分かるのは、Plugin が単なる設定ファイルではないことです。
Plugin は、インストール画面でどう見えるか、何ができるか、どの外部サービスや権限が関係するかまで含めて設計する必要があります。
Marketplaceは「配布リスト」
Plugin は marketplace 経由で共有できます。
ここでいう marketplace は、必ずしも大きな公開ストアだけではありません。
プロジェクト用。
チーム用。
個人用。
リポジトリ用。
そういう単位でも作れます。
公式ドキュメントでは、marketplace は plugins の JSON catalog であり、repo、team、personal workflow 向けに curated list を作れると説明されています。$REPO_ROOT/.agents/plugins/marketplace.json は repo-scoped list、~/.agents/plugins/marketplace.json は personal list として使えます。(OpenAI Developers)
たとえば、repo 用 marketplace はこういう形です。
{
"name": "local-repo",
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}
ここで大事なのは、Plugin と Marketplace は別物だということです。
Plugin = 配布される中身
Marketplace = Pluginを並べるカタログ
公式ドキュメントでも、1つの marketplace はテスト中の単一 plugin だけを公開することも、複数 plugin を含む curated catalog に育てることもできると説明されています。(OpenAI Developers)
Plugin Directoryで使う
Codex app では、Plugins を開いて curated plugins を browse/install できます。
公式ドキュメントでは、Plugin Directory は次のカテゴリに分かれていると説明されています。
- Curated by OpenAI
- Shared with you
- Created by you
また、Codex CLI では /plugins から plugin list を開けます。CLI の plugin browser は marketplace ごとに plugin をグループ化し、install / uninstall や enabled state の切り替えができると説明されています。(OpenAI Developers)
使い方も2種類あります。
1つ目は、普通にタスクを頼む方法です。
Summarize unread Gmail threads from today
この場合、Codex がインストール済みの適切な tool を選びます。
2つ目は、@ で plugin や skill を明示的に呼ぶ方法です。
@my-plugin 今週のリリースノートを作って
公式ドキュメントでも、結果だけを直接頼む方法と、@ で特定 plugin や bundled skill を明示的に呼ぶ方法が説明されています。(OpenAI Developers)
個人的には、この2つを使い分けるのがよいと思います。
毎回同じ作業なら明示的に @plugin。
自然な依頼でよいなら、Codex に選ばせる。
権限とデータ共有はPluginの一部として考える
Plugin は便利ですが、外部サービスに接続する以上、権限とデータ共有はかなり重要です。
公式ドキュメントでは、Plugin をインストールしても既存の approval settings は引き続き適用され、接続先の外部サービスはそれぞれの authentication、privacy、data-sharing policy の対象になると説明されています。(OpenAI Developers)
また、
- bundled skills は install 後すぐ利用可能
- apps が含まれる場合は install/setup/初回利用時に sign in が必要になることがある
- MCP servers が含まれる場合は追加 setup や authentication が必要になることがある
- bundled app を通じてデータを送る場合、その app の terms/privacy policy が適用される
とも説明されています。(OpenAI Developers)
ここは見落としやすいです。
Plugin を作る側は、単に「便利な workflow」を作るだけでは足りません。
- どのデータを読むのか
- どの操作を書き込むのか
- どの外部サービスに送るのか
- どのタイミングで認証するのか
- ユーザーに何を説明するのか
ここまで含めて Plugin 設計です。
いつSkillで止めて、いつPluginにするか
ここが一番実務で悩むところだと思います。
結論としては、最初から Plugin にしなくてよいです。
公式ドキュメントでも、まだ1つの repo や personal workflow で試しているなら local skill から始めるべきだと説明されています。一方で、team に共有したい、app integrations や MCP config を bundle したい、lifecycle hooks を package したい、stable package として公開したい場合に plugin を作るべきだと説明されています。(OpenAI Developers)
自分なら、こう判断します。
| 状況 | 選ぶもの |
|---|---|
| 自分だけで使う作業手順 | local skill |
| repo内で共有したい手順 | repo skill |
| 複数skillをまとめたい | plugin |
| Slack/GitHub/Driveなどの接続も含めたい | plugin |
| MCP server設定も一緒に配りたい | plugin |
| チームやワークスペースに配布したい | plugin |
| install画面、説明、アイコン、権限説明まで整えたい | plugin |
つまり、
Skillで作り、Pluginで配る
という順番が自然です。
Agent Skills / MCP / Plugin の関係
ここまで読むと、3つの関係がかなり整理できます。
| 概念 | 本質 | AIに渡すもの |
|---|---|---|
| Agent Skills | 作業手順のパッケージ | instructions、references、scripts |
| MCP | 外部接続プロトコル | tools、resources、prompts |
| Codex Plugin | 配布可能なワークフローパッケージ | skills、apps、MCP servers、hooks、assets |
もう少し実務っぽく言うと、こうです。
Agent Skills:
この仕事は、こう進める
MCP:
この外部システムには、こう接続する
Codex Plugin:
この仕事の手順と接続を、チームに配れる形にする
この3つは競合しません。
むしろ、役割が違います。
MCP だけだと、外部ツールには接続できますが、チーム固有の仕事の進め方までは定義しにくいです。
Skill だけだと、作業手順は定義できますが、外部アプリや MCP server の設定をまとめて配布するには弱いです。
Plugin は、その2つをまとめて配れるようにします。
ここが、agentskills.io、modelcontextprotocol.io、developers.openai.com/codex/plugins を並べて読むと見えてくるポイントです。
小さく作るなら、こう始める
最初の Plugin は、大きくしない方がいいです。
いきなり「全部入りの開発支援Plugin」を作ると、たぶん失敗します。
まずは、1つの明確な業務に絞るのがよいです。
たとえば、
- リリースノート作成Plugin
- PRレビューPlugin
- セキュリティレビューPlugin
- 障害報告まとめPlugin
- 週次進捗作成Plugin
- 顧客対応ログ整理Plugin
- 社内ドキュメント検索＋要約Plugin
最初は1つの Skill だけを含む Plugin で十分です。
公式ドキュメントでも、manual creation の最初の例は、1つの skill を package する minimal plugin から始まっています。そこから MCP config、app integrations、marketplace metadata を追加できると説明されています。(OpenAI Developers)
個人的には、次の順番がよいと思います。
- local skill として作る
- 実際のタスクで使う
- description と手順を改善する
- 必要なら scripts を追加する
- 外部接続が必要なら app / MCP を追加する
- チーム配布したくなったら plugin にする
- marketplace に載せる
- install surface の説明、権限、アイコンを整える
この順番なら、Plugin が「見た目だけ立派な空箱」になりにくいです。
Pluginで失敗しやすいところ
Plugin は便利ですが、雑に作ると危ないです。
1. 何でも入れすぎる
Plugin は bundle できるので、つい何でも入れたくなります。
でも、1つの Plugin が大きすぎると、使う側が何を入れているのか分からなくなります。
「PRレビューPlugin」なのか。
「開発支援Plugin」なのか。
「社内全部入りPlugin」なのか。
スコープは狭い方がよいです。
2. description が弱い
Plugin や Skill は、使うタイミングが大事です。
Skills では description が implicit invocation に関係します。公式の Skills ドキュメントでも、implicit matching は description に依存するため、scope と boundary が明確な concise descriptions を書き、key use case と trigger words を前に置くべきだと説明されています。(OpenAI Developers)
これは Plugin に入れる Skill でも同じです。
3. 権限説明が薄い
Plugin に Apps や MCP servers が含まれると、外部サービスへのアクセスが発生します。
何を読むのか。
何を書けるのか。
どの操作に approval が必要なのか。
ここを曖昧にすると、チームに配布しにくくなります。
4. Hooksを軽く見る
Hooks は強力ですが、実行される処理です。
公式ドキュメントでも、Plugin-bundled hooks はインストールや有効化だけでは自動的に trust されず、ユーザーがレビューして trust するまでスキップされると説明されています。(OpenAI Developers)
これは安全側の設計です。
Hook を含めるなら、何をする hook なのかを明確に書く必要があります。
まとめ
Codex Plugin は、AI に「機能を追加する」ためだけの仕組みではありません。
本質は、
- Skills を配布可能にする
- Apps との接続をまとめる
- MCP server 設定を bundle する
- Hooks や assets も含めて installable package にする
- Marketplace 経由でチームやプロジェクトに共有する
という点です。
Agent Skills は、AI に仕事のやり方を渡します。
MCP は、AI と外部世界をつなぎます。
Codex Plugin は、それらをチームに配れる形にします。
これから AI エージェントを実務で使うなら、重要なのはモデル単体の性能だけではありません。
仕事の手順を Skill にする
外部接続を MCP / App で持つ
それらを Plugin として配布する
この3層を設計できるかが、かなり重要になると思います。