Codexに自分の道具を足す：MCPサーバー、スキル、フック、プラグインの作り方と配り方を、公式の手順で確かめる

この記事は、公式ドキュメントと公式GitHubを2026年10月24日に読んでまとめたもので、実際に使って確かめた記録ではありません。運営者はCodexを入れていますが、使い心地はこの記事には書いていません。コマンド、設定名、JSONやTOMLの例は公式の表記を写したもので、動作確認はしていません。公式の文章は要約の形で取得したため、全文を写せていない例があります。その場合は、どこまでが公式でどこからが僕らの組み立てかを、本文で分けて書きます。

先に結論

• 足す順番の目安。 公式がこの順を勧めているわけではありませんが、MCPは「外へつながる」、スキルは「手順を渡す」、フックは「割り込む」、プラグインは「配る」という役割の違いがあります。まず役割で選ぶと迷いません（比較は次の節の表）。
• いちばん広い穴。 フックの PreToolUse が、公式が書いていない形の値（たとえば ask）を返すと、フックは「失敗」として扱われ、ツール呼び出しは続行されます。守りのつもりのフックが、書き間違いで素通りになる仕組みです。
• MCPの注意の中心。 --oauth-client-secret で渡したシークレットは config.toml に保存されます。公式は、そのファイルを非公開にして、バージョン管理に入れないよう書いています（「平文」という語は、読んだ範囲では見つかりませんでした）。そして、読んだ範囲では、第三者のMCPサーバーを入れるときの信頼についての警告は、MCPのページに見つかりませんでした。
• 配り方の分かれ目。 自分や自分のチームで使うなら、リポジトリの .agents/plugins/marketplace.json を共有するのが、公式に書かれた手順です。公開ディレクトリに出す場合は、審査があり、フックを含むZIPは出せません。

前提：用語をそろえる

• MCPサーバー：外部のサービスやデータを、Codexの「道具」として見せるプログラムです。手元で起動する方式（STDIO）と、URLで呼ぶ方式（Streamable HTTP）があります。
• スキル：特定の作業の指示と資料をまとめた、再利用できるフォルダです。中心は SKILL.md です。
• フック：エージェントの動きの途中（ツールの実行前後、会話の開始や終了など）で、スクリプトやMCPのツールを動かす仕組みです。
• プラグイン：スキル、MCPサーバー、フックなどを1つにまとめて、インストールできる形にした束です。
• マーケットプレイス：プラグインの一覧を書いたファイル（marketplace.json）と、その置き場所のことです。
• 承認とサンドボックス：前のガイド（02）に書いたとおり、Codexが何をできるかの囲いと、囲いを越えるときに人へ聞くかどうかの設定です。今回の部品は、この囲いとの関係が、部品ごとに違います。

4つの部品の違い：どれで何を足すのか

公式ドキュメントの説明から、役割と置き場所を並べます。最後の列は、権限や信頼の扱いの要点です。詳しくは各節と「権限との関係」の節に書きます。

使い分けの目安は、公式の「Skills & Plugins」にあります。指示だけで足りるならスキル、外部サービスや他の道具も組み合わせたいならプラグイン、という整理です。

MCPサーバーを足す

コマンドで足す

公式のMCPのページに載っている形は、次のとおりです。

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

-- は、Codex自身のフラグと、起動するサーバーのコマンドを分ける区切りです。--url を付けるとStreamable HTTPのサーバーになります。ページに書かれた説明は、次のとおりです。

• --env KEY=VALUE は、サーバーを起動するときの環境変数で、繰り返して指定できます。
• --oauth-client-id は、事前登録したOAuthクライアントのIDです。
• --oauth-client-secret は、機密クライアントのシークレットです。公式は、値を環境変数から読むように書き、Codexはこれを config.toml に保存する、と明記しています。

6つのサブコマンド（公式GitHubのソースから）

公式のコマンド一覧のページは、読んだ範囲では、mcp について add、login、logout の説明しか文章になっていませんでした。フラグの表が画面の部品で、要約に出てこなかったためです。そこで、公式リポジトリ（openai/codex）の codex-rs/cli/src/mcp_cmd.rs の要約で補いました。ソースの要約なので、ドキュメントの記述ではなく、版によって変わりうる点に注意してください。

あわせて、add と remove は、名前に使える文字を、英数字、-、_、:、@、/、. に限っています（ソースの記述）。remove が資格情報を消さないことは、見落としやすい点です。サーバーをやめるときは、logout も使う、という手順になります。

会話の中では、/mcp で動いているサーバーを見られます。コマンド一覧のページには、/mcp verbose でサーバーの詳細、/mcp login <名前> でログインができる、とあります。

デスクトップアプリとIDE拡張には、設定画面からサーバーを足す入口があります。CLI、アプリ、IDE拡張は、同じホストの上では同じMCP設定を共有する、とMCPのページに書かれています。

設定ファイルで書く

設定は、~/.codex/config.toml、または信頼したプロジェクトの .codex/config.toml の、[mcp_servers.<名前>] に書きます。公式の例は次のとおりです。

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

env_vars は、親の環境にある変数を、サーバーへ引き渡す指定です。env のように値を書かずに済むので、ファイルに秘密が残りません。

主な項目を、公式の表（MCPのページ、Sample Configuration、設定リファレンス）から表にまとめます。

承認の方式のうち、writes は、「読み取り専用と印が付いていないツール」だけ確認する方式だと、MCPのページに説明があります。auto と approve が具体的に何をするかは、名前以上の説明を、読んだ範囲では見つけられませんでした。

ツールを絞る：許可リスト、拒否リスト、承認の方式

権限との関係で、いちばん手が届きやすいのが、サーバーが出す道具を絞る設定です。公式のMCPページの例（chrome_devtools）は、次のキーを使っています。ページの要約から、キーと値の断片を取り出したもので、TOMLの組み立てと、起動の設定を省いたことは僕らの整理です。

[mcp_servers.chrome_devtools]
# command や url の設定は省略
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]   # enabled_tools のあとに適用される
default_tools_approval_mode = "prompt"

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

読み方は、次のとおりです。enabled_tools に挙げたものだけが残り、そこから disabled_tools のものが引かれるので、この例の最終的な道具は open だけになります（公式の注釈どおり、拒否は許可のあとに適用されます）。サーバー全体の承認は prompt で、open だけ approve に上書きしています。output_token_limit は、道具1回の出力の予算で、公式は「標準の20%の余裕を足す前」の数と書いています。あわせて、mcp_optional_startup_grace_ms（既定1000ミリ秒）は、必須でないサーバーを、最初の道具一覧を作るときに待つ時間で、0 にすると、サーバーごとの startup_timeout_sec まで待ちます。OAuthの戻り先に独自のパスや外部のURLが要るときは、mcp_oauth_callback_url があります。

認証：3通りと、OAuthの細かい設定

設定リファレンスとMCPのページから、HTTPサーバーの認証を整理します。

OAuthの登録方式は、CIMD（対応していれば既定）、DCR、設定した client_id を使う方法（登録を飛ばす）の3つです。ログインのときだけ --oauth-client-registration auto|cimd|dcr で変えられ、この指定は config.toml には保存されません。コールバックの既定は http://127.0.0.1/callback で、固定のポートが要るサーバー向けに、全体の mcp_oauth_callback_port と、サーバーごとの oauth.callback_port があります。サーバーごとの指定のほうが優先されます。

入れる前に確かめたい、公式の注意

• client_secret は config.toml に保存されます。公式は、そのファイルを非公開にして、バージョン管理に入れないよう書いています。add のコマンドで秘密を渡しても、同じ場所に保存されます。
• コマンドのネットワークプロキシは、MCPサーバーへの接続を絞りません。それらは別の制御の対象だ、と「Agent approvals & security」のページにあります。
• 副作用のあるMCPのツールは、シェルのコマンドでなくても、承認を求められることがあります。「破壊的」という注釈をつけて公開しているツールは、必ず承認の対象になり、「読み取り」の注釈はそれより優先されます。
• ローカルのMCPサーバーは、クラウドのコンテナでは使えないことがあります。ChatGPTのWeb版は、手元のCodexの設定を読みません。
• プラグインが持ってくるMCPサーバーは、plugins."<プラグイン名>".mcp_servers.<サーバー名> で、有効かどうかとツールの方針は変えられますが、起動コマンドは変えられません。
• 第三者のMCPサーバーを入れるときの信頼については、CLI向けのMCPのページを読んだ範囲では、警告が見つかりませんでした。公式がどこかに書いている可能性はありますが、確認できていません。一方、「Agent approvals & security」のページには、取得した内容を通じて、信頼できない指示にエージェントが従うこと（プロンプトインジェクション）の注意があります。

スキルを作る

SKILL.mdの形と、フォルダの構成

公式の「Build skills」にある最小の形は、次のとおりです。

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

name と description が必須で、読んだページには、ほかの項目の記載はありませんでした。フォルダの構成は、次のとおりです。

公式リポジトリ（openai/skills）の skill-creator は、より細かい作法を書いています。このリポジトリは「deprecated（非推奨）」と表示されていて、現在の例は openai/plugins を見るよう案内されています。そのため、次の内容は、旧リポジトリの中のスキルの要約として読んでください。

• name は、小文字、数字、ハイフンで、64文字未満、フォルダ名と合わせる。
• 「いつ使うか」は、すべて description に書く。本文は、スキルが選ばれてから読まれるため。
• 本文は500行以内を目安にし、細かい内容は references/ に分ける。
• 公式の説明にも、整合しない点があります。文章では「name と description 以外の項目を入れない」としながら、同じ文書の例には metadata の項目があります。

agents/openai.yaml の項目は、公式のページに次のように書かれています。

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

agents/openai.yaml は、公式が「ChatGPTのデスクトップアプリでの表示（UIメタデータ）の設定」に使うと書いているファイルで、interface はその表示用の項目です。allow_implicit_invocation は既定が true で、false にすると、依頼の文章からは自動で選ばれなくなりますが、$スキル名 で自分から呼ぶことはできます。dependencies.tools は、スキルが必要とする道具（例ではMCPサーバー）の宣言です。必須の項目や、mcp 以外の type は、読んだページには書かれていませんでした。Sample Configurationには skill_mcp_dependency_install = true というコメント行の例がありますが、何をするかの説明や成熟度は、読んだ範囲では確認できていません。

置き場所と、見つけられ方

公式の表では、Codexは次の場所からスキルを読みます。リポジトリの中は、作業フォルダからリポジトリのルートまで、各階層の .agents/skills を調べます。

• 同じ name のスキルは、統合されません。両方が選択肢に出ます。
• シンボリックリンクのスキルのフォルダに対応し、リンク先をたどります。
• Codexはスキルの変更を自動で見つけます。反映されないときは、再起動します。config.toml を変えたあとも再起動です。
• 呼び出しは、CLIとIDE拡張で /skills か $ です。依頼が description に合うと、Codexが自分で選ぶこともできます。公式は、説明を、範囲の境界がはっきりした短い文にして、主な用途と、きっかけになる言葉を先頭に置くよう勧めています。

作り方の3通りと、入れ方

Record & Replayのページには、保存先、プランの条件、データの扱いは書かれていませんでした。公式は、秘密や機微な情報を使わないよう書いています。

ほかの人のスキルは $skill-installer で入れます（例は $skill-installer linear）。入れたあとは、再起動して読み込ませます。公式は、スキルの導入をローカルでの試用向けとし、自作のスキルを配るときはプラグインにするよう案内しています。旧リポジトリ（openai/skills）の案内では、名前で入れるものは .curated、.experimental のものはフォルダを指定します。

無効にする、数が多いとき

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

これで、消さずに無効にできます。反映には再起動が必要です。

最初に見える一覧（名前、説明、ファイルの場所）には予算があります。既定は、コンテキストの2%、または大きさが分からないときは8,000文字です。多いと、まず説明が短くされ、それでも足りないと一部が一覧から外れて、警告が出ます。予算は skills.max_context_tokens で変えられ、上限は10,000トークンです。この予算は最初の一覧だけに使われ、スキルが選ばれたあとは SKILL.md の全文が読まれます。

フックを書く

どこに書くか、どう動くか

フックは、hooks.json、config.toml の [hooks]、有効なプラグインが持ってくる設定の3か所から読まれます。主な4か所は、~/.codex/hooks.json、~/.codex/config.toml、<リポジトリ>/.codex/hooks.json、<リポジトリ>/.codex/config.toml です。

• 一致したフックは、すべて動きます。上の層のフックが、下の層のフックを置き換えることはありません。
• プロジェクトのフックは、そのプロジェクトの層を信頼しているときだけ読まれます（ユーザーとシステムのフックは、信頼していないプロジェクトでも読まれます）。同じ層に hooks.json と [hooks] が両方あると、混ぜ合わされて警告が出るので、片方に統一します。
• フックは既定で有効です。止めるには、[features] の hooks = false です。昔のキー codex_hooks は、非推奨の別名として今も動きます。管理者は、requirements.toml で強制的に止めることもできます。

構造は、イベント、一致の条件（matcher group）、処理（handler）の3段です。TOMLの例は、Sample Configurationにあります。

[hooks]
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

JSONの形は、公式のHooksのページに完全な例がありますが、要約の取得では全文を写せませんでした。断片から読み取れた構造は、次のとおりです。トップに任意の description と hooks があり、その下に、イベント名をキーとした配列、各要素に任意の matcher と、処理の配列 hooks が入ります。公式の例の断片には、"matcher": "Bash" と、"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"" がありました。リポジトリのフックは、.codex/hooks/... のような相対パスではなく、Gitのルートから解決するパスで書くよう勧められています。公式の理由は、Codexがサブフォルダから起動されることがあるためです。

処理の種類は command と mcp_tool です。prompt と agent は読み込まれても、飛ばされます。timeout を省くと、ほとんどのフックは600秒です。SessionEnd と Interrupt は省略時1秒で、上限は3秒です。

イベントと、止められるもの

matcher は正規表現の文字列で、"*"、空、省略は、すべてに一致します。apply_patch（ファイル編集）は、Edit や Write でも指定できますが、フックに渡る tool_name は、いつも apply_patch です。

ツールの対象には限りがあります。シェルコマンド、apply_patch、MCPのツール（mcp__filesystem__read_file のような名前）、一部のローカルの関数ツールは対象です。WebSearch のようなホスト側のツールは対象外です。公式は、一部の特殊なツールの経路が、既定のフックの経路を通らないことがあるため、ツールのフックは「有用なガードレールであり、完全な強制の境界ではない」と書いています。

入力と出力：標準入力のJSON、終了コード、決定

どのコマンドのフックも、標準入力でJSONを1つ受け取ります。共通の項目は、session_id、transcript_path、cwd、hook_event_name、model で、多くのイベントに permission_mode（default、acceptEdits、plan、dontAsk、bypassPermissions）が付きます。PreToolUse には、さらに turn_id、tool_name、tool_use_id、tool_input が入ります。transcript_path の形式は、安定した仕様ではないと書かれています。

出力の約束事は、次のとおりです。

• 終了コード0で出力なしは、成功です。
• 終了コード2は、多くのイベントで「止める」合図になり、標準エラーの文字が理由になります。
• 細かい決定は、JSONで返します。PreToolUse でツールを止める形は、次のとおりです。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

古い形の decision: "block" と reason も受け付けられます。公式ページの断片から、キーと文言は読めましたが、上の入れ子の形は、断片をつなげた僕らの書き方です。

最小のフックを書いて、手で確かめる

公式のページには、PreToolUse の登録の例と、止めるときのJSONの形はありますが、読んだ範囲では、Pythonのスクリプトの全文は載っていませんでした。次のスクリプトは、公式の入出力の約束（標準入力のJSON、tool_input.command、止めるときのJSON、終了コード）に合わせてこの記事で組み立てた例で、動作確認はしていません。前に載せたTOMLの pre_tool_use_policy.py に当たるものです。

#!/usr/bin/env python3
import json, sys

event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")

if "rm -rf" in command:
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "rm -rf is blocked by this hook."
        }
    }))
sys.exit(0)

Codexに登録する前に、手で試せます。実際の入力には session_id などの項目も入りますが、このスクリプトが読むのは tool_input.command だけです。

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' | python3 pre_tool_use_policy.py
echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls"}}' | python3 pre_tool_use_policy.py; echo "exit=$?"

1行目はJSONが出て、2行目は何も出ずに exit=0 になるはずです。ここで気をつけたいのは、公式が、PreToolUse の通常の文字の出力（プレーンテキスト）は無視される、と書いている点です。止めたいときは、JSONを返すか、終了コード2で理由を標準エラーに出す必要があります。また、rm -rf の文字列を探すだけの検査は、書き方を変えれば抜けられます。これは仕組みを見るための例で、守りの本体ではありません。登録したあとは、CLIの /hooks で中身を確かめて、信頼してから動きます。

PreToolUse では、ツールの入力の書き換えもできます。permissionDecision: "allow" と updatedInput を組み合わせたときだけ有効で、Bash と apply_patch では、文字列の command を含める必要があります。

信頼の仕組み

管理者が配ったもの以外のフックは、中身を確かめて信頼するまで動きません。信頼は、フックの現在のハッシュに結びつけて記録されます。そのため、新しいフックや、書き換えたフックは「要確認」の印が付き、信頼するまで飛ばされます。CLIの /hooks で、出どころの確認、新規と変更のレビュー、信頼、無効化ができます。レビューが要るフックがあると、起動時に警告が出ます。

システム、MDM、クラウド、requirements.toml から来る管理側のフックは、方針により信頼済みとして扱われ、利用者は無効にできません。外で確認済みの単発の自動化なら、--dangerously-bypass-hook-trust で、その呼び出しに限って、永続的な信頼なしにフックを動かせます。名前のとおり、公式が「信頼の確認を飛ばす」ものとして出している指定です。

フックが動かないとき：公式が挙げる理由の早見表

公式のHooksのページには、専用のデバッグの節はありません。ただ、動かない理由になりうる条件が、ページのあちこちに書かれています。それを1か所に集めました（並べ方は僕らの整理です）。

プラグインを作って配る

構成とマニフェスト

プラグインは、スキル、MCPサーバー、フックなどを、1つのフォルダにまとめたものです。ここで、公式の資料に、ずれが見えました。

• 「Package your plugin」のページは、ルートの plugin.json を、持ち運びできる形（portable）の入口として書いています。.codex-plugin/plugin.json は、互換のための形で、$plugin-creator（ChatGPTのWorkでは @plugin-creator）で作ると、こちらが必ず作られます。
• 公式のサンプル集（openai/plugins）のREADMEは、各プラグインに .codex-plugin/plugin.json が必要だと書いています。実物のマニフェスト（figma）も、この形で、skills や apps が最上位に置かれています。

どちらが現在の標準かは、読んだ範囲では、断定できません。読んだとおりに両方を並べます。

.codex-plugin/ に置いてよいのは、plugin.json だけで、フックの設定、.app.json などは、プラグインのルートに置く、とあります。足せるもの（$plugin-creator が作るもの）は、.mcp.json、.app.json、skills/、hooks/、scripts/、assets/ です。.mcp.json と .app.json は空で作られ、hooks/ は空のフォルダです。

ポータブル形式の項目は、$schema、name（ケバブケース、識別子と名前空間を兼ねる）、version、description、任意の author、homepage、repository、license、keywords です。OpenAI固有の項目は、extensions.com.openai の下に、apps、hooks、onboardingSkill、interface（displayName、shortDescription、longDescription、developerName、category、capabilities、websiteURL、privacyPolicyURL、termsOfServiceURL、defaultPrompt、brandColor、composerIcon、logo、screenshots など）を置きます。extensions.com.openai がオブジェクトとして存在すると、.codex-plugin/plugin.json の上書きを、混ぜずに丸ごと置き換える、と書かれています。パスは ./ で始め、プラグインのルートの中に収めます。

公式サンプルのfigmaのマニフェストから、主なキーだけを抜き出します（値の省略は僕らです。ほかに homepage、repository、license、keywords、各種のURLも入っています。バージョンは2026年10月24日に見えたものです）。

{
  "name": "figma",
  "version": "2.0.20",
  "description": "...",
  "author": { "name": "Figma", "url": "https://www.figma.com" },
  "skills": "./skills/",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Figma",
    "shortDescription": "Figma design-to-code workflows",
    "category": "Creativity",
    "capabilities": ["Interactive", "Read", "Write"],
    "brandColor": "#1ABCFE",
    "composerIcon": "./assets/logo-padded.png",
    "logo": "./assets/logo-padded.png"
  }
}

MCPとフックをプラグインに入れる

プラグインの .mcp.json（ポータブル形式では mcp.json）は、$schema と、名前をつけた mcpServers の表で、各サーバーに type（通信方式）と url を書きます。足場が作る .mcp.json を、名前を変えるだけでポータブル形式にはできません。type が必要だからです。認証は、各サーバーの extensions["com.openai"].auth に書きます。

クライアントのシークレットは、マニフェストに入れず、接続の設定のときに入れます。Host は、独自ヘッダーの名前に使えません。

フックは、プラグインのルートの hooks/hooks.json が既定で見つかります。extensions.com.openai.hooks で、パス、パスの配列、インラインの設定を指定すると、既定の探索が置き換わります。フックのコマンドには、環境変数 PLUGIN_ROOT（導入先のルート）と PLUGIN_DATA（書き込めるデータの場所）が渡され、互換のため CLAUDE_PLUGIN_ROOT と CLAUDE_PLUGIN_DATA も設定されます。公式が書く条件は、次のとおりです。

• フックを使えるのは、Codexのデスクトップアプリで手動で入れたプラグインだけです（「Package your plugin」のページの記載）。
• 導入や有効化だけでは、フックは信頼されません。確認して信頼するまで、飛ばされます。
• フックのスクリプトは、実行する環境に存在する必要があります。Webで導入しても、配られません。必要なら、MDMなどで配ります。

マーケットプレイス：配る側のファイル

マーケットプレイスは、marketplace.json で書きます。置き場所は、リポジトリなら $REPO_ROOT/.agents/plugins/marketplace.json、個人用なら ~/.agents/plugins/marketplace.json です。互換のため、.claude-plugin/marketplace.json も読まれます。公式サンプル集の marketplace.json の最初の項目は、次のとおりです。

{
  "name": "linear",
  "source": {
    "source": "local",
    "path": "./plugins/linear"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

トップレベルのキーは、name、interface（displayName を持つ）、plugins です。source の形は、local（path は ./ で始め、マーケットプレイスのルートの中に収める）、url、git-subdir（url、path、ref か sha）、npm（package、version、registry）です。policy.installation は、AVAILABLE、INSTALLED_BY_DEFAULT、NOT_AVAILABLE が挙がっています。authentication は、サンプルの中で ON_INSTALL と ON_USE を見ましたが、全部の値の一覧は、読んだ範囲にはありません。

Gitの ref や sha で固定できます。解決できない項目は飛ばされ、マーケットプレイス全体は失敗しません。npmのソースは、ライフサイクルスクリプトを動かさずに取得し、npm のコマンドが必要です。

コマンドと、ローカルでの試し方

CLIでは、/plugins でプラグインのブラウザが開きます。マーケットプレイスごとのタブがあり、詳細、導入と削除、有効と無効（導入済みのプラグインの上でスペースキー）を操作します。導入後は、新しいセッションで使い始めます。IDE拡張は、プラグインに対応していません（Pluginsのページ）。

ローカルで試す手順は、次のように書かれています。

1. プラグインのフォルダを、リポジトリの plugins/ などへ置く。
2. マーケットプレイスのファイルを作り、source.path をそのフォルダに向ける。
3. アプリを再起動して、表示されるか確かめる。
4. 有効と無効は、リポジトリの .codex/config.toml の [plugins."プラグイン名@マーケットプレイス名"] で切り替える。enabled = false でも、ファイルは取得される。

導入したプラグインは、~/.codex/plugins/cache/<マーケットプレイス名>/<プラグイン名>/<バージョン>/ にキャッシュされます。ローカルのプラグインのバージョンは local です。変えたときは、マーケットプレイスが指すフォルダを更新し、アプリを再起動します。更新の判定や、キャッシュの無効化の仕組みの説明は、読んだページには見つかりませんでした。

配り方の段階

管理者は、システムの config.toml や、クラウドの管理設定で、マーケットプレイスを定義することもできます。

公開ディレクトリに出す場合

「Submit plugins」のページには、次のことが書かれています。審査の期間や、承認までの目安は、読んだ範囲では見つかりませんでした。

• 提出できるのは組織のオーナーで、ほかのメンバーはApps Management Writeの権限が要ります。出すのは、組み上がったプラグインのZIPです。MCPサーバーは最初のZIPに入れる必要があり、あとから足せません。
• リモートのMCPは、安定した公開のHTTPSの接続先が必要で、1つのプラグインにつなげるMCPサーバーは1つです。ドメインの所有確認は、/.well-known/openai-apps-challenge に決められた文字列を置いて行います。
• 必須の項目に、name、displayName、shortDescription（30文字まで）、longDescription（4000文字まで）、developerName、category があります。
• 認証は、なし、OAuth、混在の3つです。APIキーやベアラートークンの流れはポータルになく、ヘッダーにトークンを入れる回避は、公開の提出では拒否されます。
• 審査の資料として、肯定のテストケース5つと否定のテストケース3つ、動画、リリースノートが要ります。
• アプリの参照（apps、.app.json）やフックを含むZIPは、今は提出できません。ローカルのMCPやデスクトップ実行のものは、別の、デスクトップ専用の経路です。
• MCPの変更は毎日スキャンされ、条件を満たせば新しいZIPなしで反映されます。メタデータやスキルの変更は、新しいZIPが必要です。

ChatGPTのWeb側には、「Plugin Creator」を @ で呼んで、会話だけでプラグインを作る別の入口もあります。ワークスペースの権限（「Use plugins」など）が要り、新しく作ったものは最初は非公開です。共有とインストールは別の操作です。

権限との関係：部品ごとに、何が効いて、何が効かないか

前のガイド（02）で書いたサンドボックスと承認が、今回の4つの部品にどう関わるかを、公式の記載から整理します。読めなかった所は、そう書きます。

プロジェクトの信頼も関わります。信頼していないプロジェクトでは、プロジェクトの .codex/config.toml は読まれません。ユーザーの設定に trust_level = "untrusted" を書くと、コマンドの承認を求め、プロジェクトの設定も読まない、と「Agent approvals & security」にあります。信頼していない場所で、プロジェクトのMCP、フック、スキルが効かないのは、この仕組みのためです。

クラウドとの関係も、公式が書いています。クラウドの管理（orchestration）では、コマンドのフック、ローカルの設定やプラグイン由来のフックは、使えません。管理者が定めたリモートのMCPフックだけが、対象になりえます。これらのMCPフックは、Compliance APIの完全な監査の記録にはならない、とも書かれています。

最初の10分でやること

公式に書かれた手順の範囲で、手を動かす順番を並べます。順番の組み立ては僕らの整理で、公式の推奨そのものではありません。

1. MCPを1つ足す（3分）。 公式の例のとおり、codex mcp add context7 -- npx -y @upstash/context7-mcp を実行し、codex mcp list で状態を見ます。会話の中では /mcp で、動いているサーバーを確かめます。入れたあとに消すなら、codex mcp remove context7 です。ログインが要るサーバーなら、あとで codex mcp logout も使います。
2. スキルを1つ作る（4分）。 Codexで $skill-creator を呼び、毎回頼んでいる作業を、用途、きっかけ、指示のみ、の順に答えて下書きにします。置き場所は、そのリポジトリだけなら .agents/skills、どこでも使うなら $HOME/.agents/skills です。反映されないときは、再起動します。
3. フックは見るだけにする（3分）。 最初は新しいフックを書かずに、CLIの /hooks を開いて、読み込まれているフックと、信頼の状態を見ます。止める系のフックは、config.toml に書く前に、スクリプトを単体で動かして、標準入力のJSONを流し込み、終了コードと出力を確かめる、という順が安全です。

プラグインは、この10分には入れていません。まずMCP、スキル、フックの単体で動くことを確かめてから、まとめる段階に進むほうが、問題の切り分けが楽になると考えるためです。

次の30分：最小のプラグインを作って、ローカルで試す

10分の次の段階です。公式の「ローカルで試す」手順（Build plugins）に出てくる形を、そのまま順に並べます。手順の区切りと所要時間はこの記事の整理で、動作確認はしていません。

1. フォルダと入口を作る。 木の形は次のとおりです。スキルは、ルートの skills/ に置くと、自動で見つかり、マニフェストに skills の項目は要りません。

my-first-plugin/
├── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow"
}

1. スキルを書く。 skills/hello/SKILL.md に、前に見た name と description と、本文の指示を書きます。
2. 置いて、マーケットプレイスに登録する。 共有したいなら、フォルダを $REPO_ROOT/plugins/my-plugin に置き、$REPO_ROOT/.agents/plugins/marketplace.json を作ります。個人用なら、~/.codex/plugins/my-plugin に置き、~/.agents/plugins/marketplace.json を作ります。公式の例のファイルは次のとおりです（フォルダ名は、公式の例では my-plugin です。上の木の名前と合わせてください）。

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": { "source": "local", "path": "./plugins/my-plugin" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}

1. 再起動して、確かめる。 公式の手順は、ChatGPTのデスクトップアプリを再起動して、プラグインの一覧に出ることを確かめる、です。CLIでは /plugins が入口です。中身を変えたら、フォルダを更新して、また再起動します。
2. 任意で、有効と無効を設定に書く。 リポジトリの .codex/config.toml に、[plugins."my-plugin@local-repo"] と enabled = true を書きます。enabled = false なら、入れたまま、そのプロジェクトだけ止められます。

source.path は、マーケットプレイスのルートから解決され、.agents/plugins/ からではない、と公式にあります。ここでつまずきやすいので、先に見ておくと楽です。

僕らの見立て

ここからは見立てです。公式の整理から組み立てたもので、公式の推奨ではありません。

• フックは「見張り」より「記録と補助」から。 公式が、ツールのフックを強制の境界ではないと書き、PreToolUse が ask などを返すと素通りになる、と書いているので、取り返しのつかない操作を止める目的は、承認の方針とサンドボックスのほうに寄せ、フックは、整形、通知、記録、文脈の追加のような、失敗しても困らない使い方から始めるほうがよさそうです。
• スキルを .agents/skills に自動で書かせるときは注意。 .agents は、書き込める範囲の中でも、読み取り専用に守られるパスに挙がっています。Codexに自分のリポジトリのスキルを書かせるときは、承認を求められる可能性があります。ただし、これは2つの記述をつなげた推測で、実機では確かめていません。
• MCPは、必須と任意を分ける。 required = true は、そのサーバーがないと起動に失敗するので、自動化の中で使うときに、動かない状態に気づく助けになります。普段の対話では、起動が遅いサーバーを、必須にしないほうが、使い心地は保てると考えます。

気をつけること

• この記事は、実際に使って確かめた記録ではありません。運営者はCodexを入れていますが、使い心地はこの記事には書いていません。コマンド、設定名、数値、JSONとTOMLの例は、公式の表記を写したもので、動作確認はしていません。「ツールを絞る」と「最小のフック」の例は、公式の断片から僕らが組み立てたものです。
• 取得したのは要約です。フックのJSONの完全な例、公式のスキルの完全な例、公式のプラグインの完全なマニフェストの例は、全文を写せていません。本文で「僕らが断片からつないだ」「僕らが省略した」と書いた所は、公式そのものではありません。
• 「Package your plugin」のページが書くポータブル形式（ルートの plugin.json）と、公式サンプル集の実物（.codex-plugin/plugin.json）の関係は、読んだ範囲では、どちらが標準かを断定できません。作る前に、公式の最新のページを見てください。
• 設定リファレンスは、途中で文字数の上限に当たり、skills.*、plugins.<id>、marketplaces、hooks の状態、trust_level の定義の行は、読めていません。Sample Configurationにも、[plugins."..."] と [marketplaces.*] はありませんでした。
• コマンド一覧のページは、フラグの表と各コマンドの成熟度の列が、読めませんでした。「Feature Maturity」のページは、ラベルの定義だけで、機能ごとの割り当てはありませんでした。この記事の「非推奨」「実験的」は、各ページの文章に書かれていたものだけです。
• 読んだ範囲で成熟度に関する記載があったものは、次のとおりです。experimental_environment は実験的、codex mcp-server は削除済み、codex app-server は予告なく変わりうる、codex_hooks は非推奨の別名、prompt と agent のフックは読み込まれても飛ばされる、「Sign in with ChatGPT」はベータ、旧リポジトリ openai/skills は非推奨、と書かれています。MCP、スキル、フック、プラグインの本体について、ベータや実験的という表示は、読んだ範囲では見つかりませんでした。
• openai/skills の skill-creator と mcp_cmd.rs は、公式のGitHubですが、ドキュメントではなくソースの要約です。版によって変わりえます。
• 公式のページには日付の記載がなく、developers.openai.com から learn.chatgpt.com へ転送されるページがありました（読んだのは転送先です）。
• 読めなかったページがあります。Rulesのページ、プラグインの管理者向けのページ、「Build an MCP server」、openai/plugins の各プラグインの中身は、読めていません。
• この記事は、セキュリティの助言ではありません。外部のMCPサーバー、スキル、フック、プラグインを入れるときは、中身を自分で読み、組織の方針を確認してください。

出典

• Model Context Protocol（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Model Context Protocol（CLI向けの表示、Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Build skills（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Skills & Plugins（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Record & Replay（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Hooks（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Plugins（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Build plugins（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Build plugins（ローカルで試す手順と管理者向けの記載、OpenAI Developers、日付の記載なし、確認日2026-10-24）
• Package your plugin（OpenAI、日付の記載なし、確認日2026-10-24）
• Submit plugins（OpenAI、日付の記載なし、確認日2026-10-24）
• Developer commands（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Sample Configuration（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Configuration Reference（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Agent approvals & security（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• Feature Maturity（Codex Docs、OpenAI、日付の記載なし、確認日2026-10-24）
• openai/codex の mcp_cmd.rs（GitHub公式リポジトリ、main、日付の記載なし、確認日2026-10-24）
• openai/plugins（GitHub公式リポジトリ、README、日付の記載なし、確認日2026-10-24）
• openai/plugins の marketplace.json（GitHub公式リポジトリ、main、日付の記載なし、確認日2026-10-24）
• openai/plugins の figma の plugin.json（GitHub公式リポジトリ、main、日付の記載なし、確認日2026-10-24）
• openai/skills（GitHub公式リポジトリ、非推奨と表示、日付の記載なし、確認日2026-10-24）
• openai/skills の skill-creator（GitHub公式リポジトリ、main、日付の記載なし、確認日2026-10-24）