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 <repo_root>/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 の表示順に含める場合は、リポジトリのマーケットプレイスエントリーを生成または更新します。

# marketplace.json always lives at <repo-root>/.agents/plugins/marketplace.json
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

ホームローカルプラグインの場合は、<home> をルートとして扱い、次のようにします。

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> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> は、プラグインフォルダー <plugin-name> を作成するディレクトリです（例：~/code/plugins）。

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

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

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

• marketplace.json は常に <repo-root>/.agents/plugins/marketplace.json に配置されます。
• ホームローカルプラグインの場合も、<home> をルートとして同じ規則を使用します。 ~/.agents/plugins/marketplace.json と ./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 を使用します。

• <repo-root>/.agents/plugins/marketplace.json がまだ存在しない場合は、トップレベルの "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> にします。

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

プラグインマニフェストとマーケットプレイスのエントリーの正確な標準 JSON サンプルについては、次を参照してください。

• references/plugin-json-spec.md

検証

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

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