プラグイン作成

プラグイン作成 は何をしますか？

クイックスタート

1. スキャフォールドスクリプトを実行します:

# プラグイン名は小文字のハイフン区切りに正規化され、64 文字以下である必要があります。
# 生成されるフォルダ名と plugin.json の name は常に同じです。
# スキルルート (この `SKILL.md` を含むディレクトリ) から実行します。
# デフォルトでは `~/plugins/<plugin-name>` に作成されます。
python3 scripts/create_basic_plugin.py <plugin-name>

2. リクエストで特定のメタデータが指定されている場合は、<plugin-path>/.codex-plugin/plugin.json を編集します。 スキャフォールドは有効なデフォルトで始まり、[TODO: ...] プレースホルダーを含めてはいけません。

3. Codex UI の順序にプラグインを表示させたい場合は、個人マーケットプレイスエントリを生成または更新します:

# 個人マーケットプレイスエントリはデフォルトで `~/.agents/plugins/marketplace.json` にあります。
python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

デフォルトの personal マーケットプレイス名がすでに使用中またはインストールされており、別の新しいマーケットプレイスファイルをシードする必要がある場合にのみ --marketplace-name <name> を指定します:

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

ユーザーが明示的にその宛先を要求した場合にのみ、リポジトリ/チームマーケットプレイスを使用します:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

ユーザーがマーケットプレイスパスを指定した場合は、再インストールするよう指示する前に、そのマーケットプレイスが実際にインストールされていることを確認してください。デフォルトの個人マーケットプレイスファイル ~/.agents/plugins/marketplace.json は暗黙的に検出されますが、他のマーケットプレイスパスは検出されません。Windows では、ユーザープロファイルの下にある同等のパスを使用します。

4. 必要に応じて、オプションのコンパニオンフォルダを生成/調整します:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> は、プラグインフォルダ <plugin-name> が作成されるディレクトリです (例: ~/plugins)。

5. 生成されたプラグインを引き渡す前に、次を実行します:

python3 scripts/validate_plugin.py <plugin-path>

開発中に既存のローカルプラグインを更新する場合は、スキャフォールドフローをそのまま維持し、マーケットプレイスファイルを手動編集する代わりに参照を使用します:

python3 scripts/update_plugin_cachebuster.py <plugin-path>

ユーザーが明示的に特定のオーバーライドを要求しない限り、ヘルパーのデフォルトキャッシュバスターを優先します。既存のローカルプラグインを反復処理する際の期待されるキャッシュバスターと再インストールフローについては、references/installing-and-updating.md を参照してください。

このスキルが作成するもの

• デフォルトのマーケットプレイスバックアップスキャフォールドは、~/.agents/plugins/marketplace.json にある個人マーケットプレイスファイルを使用し、プラグインは通常 ~/plugins/<plugin-name>/ に保存されます。
• /<parent-plugin-directory>/<plugin-name>/ にプラグインルートを作成します。
• 常に /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json を作成します。
• インジェストパスが受け入れる検証済みスキーマ形状でマニフェストを埋めます。
• --with-marketplace が設定されている場合、~/.agents/plugins/marketplace.json を作成または更新します。
  • マーケットプレイスファイルがまだ存在しない場合は、最初のプラグインエントリを追加する前に個人マーケットプレイスルートをシードします。
• <plugin-name> は、スキル作成の命名規則を使用して正規化されます:
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • アンダースコア、スペース、句読点は - に変換されます
  • 結果は小文字のハイフン区切りで、連続するハイフンはまとめられます
• オプションの作成をサポート:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

マーケットプレイスワークフロー

• 個人マーケットプレイスの作成はデフォルトで ~/.agents/plugins/marketplace.json になります。ここで「個人マーケットプレイス」とは、そのパスにあるマーケットプレイスファイルを意味します。
• リポジトリ/チームマーケットプレイスの作成は、ユーザーが明示的に要求した場合にのみ、--path と --marketplace-path の両方を介してオプトインされます。
• --marketplace-name は例外パスです。デフォルトの personal マーケットプレイス名がすでに使用中で、別の新しいマーケットプレイスファイルをシードする必要がある場合にのみ使用します。
• --marketplace-name を使用して、既存のマーケットプレイスファイルの名前をその場で変更しないでください。ファイルが既に存在する場合、そのトップレベルの name はすでに一致している必要があります。
• ユーザーが別のマーケットプレイスパスを指定した場合は、そのマーケットプレイスを codex plugin marketplace add で明示的にインストールする必要があるものとして扱います。
• 任意の marketplace.json ファイルからマーケットプレイス名が必要な場合は、scripts/read_marketplace_name.py を優先します。引数なしではデフォルトの個人マーケットプレイスを読み取り、明示的なパスを指定するとリポジトリ/チームマーケットプレイスでも機能します。
• どちらの場所でも、生成されるソースパスは ./plugins/<plugin-name> のままです。
• マーケットプレイスルートメタデータは、トップレベルの name とオプションの interface.displayName をサポートします。
• plugins[] 内のプラグインの順序は、Codex でのレンダリング順序として扱います。ユーザーが明示的にリストの並べ替えを要求しない限り、新しいエントリを追加します。
• displayName は個々の plugins[] エントリではなく、マーケットプレイス interface オブジェクトに属します。
• 生成される各マーケットプレイスエントリには、以下すべてを含める必要があります:
  • policy.installation
  • policy.authentication
  • category
• 新しいエントリのデフォルト:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• ユーザーが明示的に別の許可された値を指定した場合にのみ、デフォルトをオーバーライドします。
• 許可される policy.installation の値:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• 許可される policy.authentication の値:
  • ON_INSTALL
  • ON_USE
• policy.products はオーバーライドとして扱います。ユーザーが明示的に製品ゲーティングを要求しない限り、省略します。
• 生成されるプラグインエントリの形状は次のとおりです:

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

• --force は、同じプラグイン名の既存のマーケットプレイスエントリを意図的に置き換える場合にのみ使用します。

• ターゲットのマーケットプレイスファイルがまだ存在しない場合は、トップレベルの "name"、"interface" オブジェクト ( "displayName" を含む)、および plugins 配列を作成してから、新しいエントリを追加します。

• 新しいマーケットプレイスファイルの場合、ルートオブジェクトは次のようになります:

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

必須の動作

• 外側のフォルダ名と plugin.json の "name" は常に同じ正規化されたプラグイン名です。
• 必須の構造を削除しないでください。.codex-plugin/plugin.json を存在させたままにします。
• プラグインマニフェストに [TODO: ...] プレースホルダーを残さないでください。
• コンパニオンファイルが実際に作成されない限り、apps と mcpServers を plugin.json に含めないでください。
• 検証で拒否される、サポートされていないプラグインマニフェストフィールド (hooks を含む) は省略します。
• 既存のプラグインパス内にファイルを作成する場合は、上書きが意図的である場合にのみ --force を使用します。
• 既存のマーケットプレイスの interface.displayName を保持します。
• マーケットプレイスエントリを生成するときは、値がデフォルトであっても、常に policy.installation、policy.authentication、および category を書き込みます。
• ユーザーが明示的にそのオーバーライドを要求した場合にのみ、policy.products を追加します。
• マーケットプレイスの source.path は、選択されたマーケットプレイスルートからの相対パスとして ./plugins/<plugin-name> のままにします。
• --marketplace-name は、personal という名前がすでに他の場所で使用中またはインストールされているため、その名前を使用すべきでない新しいマーケットプレイスファイルを作成する場合にのみ使用します。
• Codex がマーケットプレイスファイルを書き込むために承認を必要とする場合は、先に進む前にその承認を求めてください。ユーザーが自分で書き込みを実行したい場合は、正確なスキャフォールドコマンドを提供し、その後、検証または後続のプラグイン編集から続行し、ワークフローを曖昧なままにしないでください。
• 開発中に既存のローカルプラグインを更新する場合は、マーケットプレイス設定や marketplace.json を手動で編集しないでください。references/installing-and-updating.md および scripts/update_plugin_cachebuster.py に記載されている更新フローを使用してください。
• デフォルトの個人マーケットプレイスフローの場合、ユーザーに codex plugin marketplace add を実行するように指示しないでください。そのコマンドは明示的な非デフォルトのマーケットプレイス設定用であり、標準の ~/.agents/plugins/marketplace.json パス用ではありません。
• ユーザーが非デフォルトの --marketplace-path を提供した場合は、再インストール手順を指示する前に、そのマーケットプレイスがインストールされていることを確認してください。その明示的なマーケットプレイスがまだ設定されていない場合は、codex plugin marketplace add <path-to-marketplace-root> を使用します。
• ワークフローがマーケットプレイスバックアップのプラグインを作成または更新した場合は、最後のユーザー向け応答を短い Codex アプリのハンドオフで終了します。Codex アプリで表示するには: と言い、表示 <正規化されたプラグイン名> と 共有 <正規化されたプラグイン名> を Markdown リンクとして書き込みます。生の URL やコードスパンは使用しないでください。
• View ディープリンクは codex://plugins/<正規化されたプラグイン名>?marketplacePath=<絶対的な marketplace.json パス> を使用します。Share ディープリンクは同じ URL に &mode=share を追加して使用します。
• プレースホルダーを、スキャフォールドされたプラグインの実際の正規化されたプラグイン名と絶対的な marketplace.json パスに置き換えます。必要に応じて、パスセグメントとクエリ値を URL エンコードします。
• これらのディープリンクに pluginName または hostId クエリパラメータを追加しないでください。Codex はユーザーがリンクをクリックした後に両方を派生させます。
• マーケットプレイスエントリが作成または更新されなかった場合は、表示 <正規化されたプラグイン名> または 共有 <正規化されたプラグイン名> リンクを発行しないでください。

正確な仕様サンプルへの参照

プラグインマニフェストとマーケットプレイスエントリの両方の正確な正規サンプル JSON については、以下を使用します:

• references/plugin-json-spec.md
• references/installing-and-updating.md (既存のローカルプラグインを反復処理する際の更新/再インストールのガイダンス、および再インストール後の新しいスレッドピックアップ動作について)

検証

SKILL.md を編集した後、次を実行します:

python3 ../skill-creator/scripts/quick_validate.py .

生成されたプラグインを引き渡す前に、次を実行します:

python3 scripts/validate_plugin.py <plugin-path>