grahama1970/plugin-creator

プラグインクリエイター

クイックスタート

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

# プラグイン名は小文字のハイフン区切りに正規化され、64 文字以内である必要があります。
# 生成されるフォルダ名と plugin.json の名前は常に同じです。
# スキルルート（この 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
  • アンダースコア、スペース、句読点は - に変換されます
  • 結果は小文字のハイフン区切りで、連続するハイフンは1つにまとめられます
• オプションで次の作成をサポートします:
  • 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 アプリでこれを表示するには: と言い、View <正規化されたプラグイン名> と Share <正規化されたプラグイン名> を Markdown リンクとして記述します。生の URL やコードスパンは使用しません。
• View ディープリンクは codex://plugins/<正規化されたプラグイン名>?marketplacePath=<絶対的な marketplace.json パス> を使用します。Share ディープリンクは同じ URL に &mode=share を追加して使用します。
• プレースホルダーを、スキャフォールディングされたプラグインの実際の正規化されたプラグイン名と絶対的な marketplace.json パスに置き換えます。必要に応じてパスセグメントとクエリ値を URL エンコードします。
• これらのディープリンクに pluginName または hostId クエリパラメータを追加しないでください。Codex はユーザーがリンクをクリックした後に両方を導出します。
• マーケットプレイスエントリが作成または更新されなかった場合は、View <正規化されたプラグイン名> または Share <正規化されたプラグイン名> リンクを出力しないでください。

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

プラグインマニフェストとマーケットプレイスエントリの両方の正確な正規サンプル 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>