plugin-creator

プラグイン作成ツール

クイックスタート

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

  # Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
  # The generated folder and plugin.json name are always the same.
# Run from repo root (or replace .agents/... with the absolute path to this SKILL).
# By default creates in ~/plugins/<plugin-name>.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

2. <plugin-path>/.codex-plugin/plugin.json を開き、[TODO: ...] プレースホルダーを置き換えます。

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

# Personal marketplace entries default to ~/.agents/plugins/marketplace.json.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

現在の Git リポジトリに .agents/plugins/marketplace.json がすでにあり、プラグインが個人用かチームと共有するものかをユーザーが指定していない場合は、マーケットプレイスのエントリーを生成する前に確認します。 リポジトリのマーケットプレイスを選択した場合は、次を使用します。

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path ./plugins \
  --marketplace-path ./.agents/plugins/marketplace.json \
  --with-marketplace

4. 必要に応じて、オプションの関連フォルダーを生成または調整します。

python3 .agents/skills/plugin-creator/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> を作成するディレクトリです（例：~/code/plugins）。

このスキルで作成されるもの

• マーケットプレイスを使うデフォルトのスキャフォールドは個人用です。~/plugins/<plugin-name>/ と ~/.agents/plugins/marketplace.json を作成します。
• 現在の Git リポジトリに .agents/plugins/marketplace.json がすでにあり、ユーザーが個人用かチーム用かを指定していない場合は、マーケットプレイスのエントリーを生成する前に、更新するマーケットプレイスを確認します。
• プラグインのルートを /<parent-plugin-directory>/<plugin-name>/ に作成します。
• /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json を必ず作成します。
• 完全なスキーマ構造、プレースホルダー値、および完全な interface セクションを含むマニフェストを作成します。
• --with-marketplace が指定されている場合、選択したマーケットプレイスを作成または更新します。
  • マーケットプレイスファイルがまだ存在しない場合は、最初のプラグインエントリーを追加する前に、トップレベルの name と interface.displayName のプレースホルダーを設定します。
• <plugin-name> は skill-creator の命名規則に従って正規化されます。
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • アンダースコア、スペース、句読点は - に変換されます
  • 結果は小文字とハイフンで区切られ、連続するハイフンは1つにまとめられます
• 次のものをオプションで作成できます。
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

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

• 個人用プラグインでは ~/.agents/plugins/marketplace.json を使用します。
• リポジトリ／チーム用プラグインでは <repo-root>/.agents/plugins/marketplace.json を使用します。
• マーケットプレイスのルートメタデータでは、トップレベルの name と、オプションの interface.displayName がサポートされます。
• plugins[] 内のプラグインの順序は、Codex での表示順として扱います。ユーザーからリストの並べ替えを明示的に求められない限り、新しいエントリーは末尾に追加します。
• displayName はマーケットプレイスの interface オブジェクトに含めます。個々の plugins[] エントリーには含めません。
• 生成するマーケットプレイスの各エントリーには、次のすべてを含める必要があります。
  • 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"、"displayName" を含む "interface" オブジェクト、および plugins 配列を作成してから、新しいエントリーを追加します。

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

{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "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 を必ず残します。
• 人間または後続のステップで明示的に入力するまでは、マニフェストの値をプレースホルダーのままにします。
• 既存のプラグインパス内にファイルを作成する場合、上書きが意図的な場合にのみ --force を使用します。
• 既存のマーケットプレイスの interface.displayName を保持します。
• マーケットプレイスのエントリーを生成する場合、値がデフォルトであっても、必ず policy.installation、policy.authentication、category を記述します。
• ユーザーが明示的に上書きを求めた場合にのみ、policy.products を追加します。
• マーケットプレイスの source.path は、選択したマーケットプレイスのルートからの相対パス ./plugins/<plugin-name> にします。
• ワークフローでマーケットプレイスに紐づくプラグインを作成または更新した場合、ユーザー向けの最終回答の末尾に、Codex アプリへの簡潔な引き継ぎ案内を必ず付けます。To view this in the Codex app: と記載し、View <normalized plugin name> および Share <normalized plugin name> を、生の URL やコードスパンではなく Markdown リンクとして記述します。
• View のディープリンクには、codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path> を使用します。Share のディープリンクには、同じ URL に &mode=share を付けたものを使用します。
• プレースホルダーは、スキャフォールドされたプラグインの実際の正規化済みプラグイン名と絶対パスの marketplace.json パスに置き換えます。必要に応じて、パスのセグメントとクエリ値を URL エンコードします。
• これらのディープリンクに pluginName や hostId のクエリパラメーターを追加しないでください。ユーザーがリンクをクリックした後、Codex が両方を取得します。
• マーケットプレイスのエントリーが作成も更新もされていない場合は、View <normalized plugin name> または Share <normalized plugin name> のリンクを出力しないでください。

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

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

• references/plugin-json-spec.md

検証

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

python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator