plugin-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plugin Creator

插件创建工具

Quick Start

快速开始

Run the scaffold script:

bash

  # 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.

运行脚手架脚本：

bash

  # 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. Open `<plugin-path>/.codex-plugin/plugin.json` and replace `[TODO: ...]` placeholders.

3. Generate or update the repo marketplace entry when the plugin should appear in Codex UI ordering:

```bash

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>


插件名称会被标准化为小写连字符格式，且长度不得超过64个字符。生成的文件夹名称和plugin.json中的名称始终保持一致。在仓库根目录下运行（或者将.agents/...替换为该SKILL的绝对路径），默认会在`<repo_root>/plugins/<plugin-name>`路径下创建插件。

2. 打开`<plugin-path>/.codex-plugin/plugin.json`，替换所有`[TODO: ...]`占位符。

3. 当你需要让插件出现在Codex UI的排序列表中时，生成或更新仓库市场条目：

```bash

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


4. Generate/adjust optional companion folders as needed:

```bash
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>

is the directory where the plugin folder

<plugin-name>

will be created (for example

~/code/plugins

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace


4. 根据需要生成/调整可选的配套文件夹：

```bash
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

）。

What this skill creates

该SKILL会生成的内容

Creates plugin root at

/<parent-plugin-directory>/<plugin-name>/

Always creates

/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json

Fills the manifest with the full schema shape, placeholder values, and the complete
```
interface
```
section.
Creates or updates
```
<repo-root>/.agents/plugins/marketplace.json
```
when
```
--with-marketplace
```
is set.
- If the marketplace file does not exist yet, seed top-level
```
name
```
  plus
```
interface.displayName
```
  placeholders before adding the first plugin entry.
```
<plugin-name>
```
is normalized using skill-creator naming rules:
- ```
My Plugin
```
  →
```
my-plugin
```
- ```
My--Plugin
```
  →
```
my-plugin
```
- underscores, spaces, and punctuation are converted to
```
-
```
- result is lower-case hyphen-delimited with consecutive hyphens collapsed

Supports optional creation of:

```
skills/
```
```
hooks/
```
```
scripts/
```
```
assets/
```
```
.mcp.json
```
```
.app.json
```

在

/<parent-plugin-directory>/<plugin-name>/

路径下创建插件根目录。

始终会生成

/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json

文件。

为清单文件填充完整的schema结构、占位符值和完整的
```
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 workflow

市场工作流

marketplace.json

always lives at

<repo-root>/.agents/plugins/marketplace.json

Marketplace root metadata supports top-level
```
name
```
plus optional
```
interface.displayName
```
.
Treat plugin order in
```
plugins[]
```
as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
```
displayName
```
belongs inside the marketplace
```
interface
```
object, not individual
```
plugins[]
```
entries.
Each generated marketplace entry must include all of:
- ```
policy.installation
```
- ```
policy.authentication
```
- ```
category
```

Default new entries to:

```
policy.installation: "AVAILABLE"
```
```
policy.authentication: "ON_INSTALL"
```

Override defaults only when the user explicitly specifies another allowed value.

Allowed

policy.installation

values:

```
NOT_AVAILABLE
```
```
AVAILABLE
```
```
INSTALLED_BY_DEFAULT
```

Allowed
```
policy.authentication
```
values:
- ```
ON_INSTALL
```
- ```
ON_USE
```
Treat
```
policy.products
```
as an override. Omit it unless the user explicitly requests product gating.
The generated plugin entry shape is:

json

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

Use
```
--force
```
only when intentionally replacing an existing marketplace entry for the same plugin name.
If
```
<repo-root>/.agents/plugins/marketplace.json
```
does not exist yet, create it with top-level
```
"name"
```
, an
```
"interface"
```
object containing
```
"displayName"
```
, and a
```
plugins
```
array, then add the new entry.
For a brand-new marketplace file, the root object should look like:

json

{
  "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"
    }
  ]
}

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
```
作为覆写字段，除非用户明确要求产品准入控制，否则省略该字段。
生成的插件条目结构如下：

json

{
  "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
```
数组，然后添加新条目。
对于全新的市场文件，根对象结构如下：

json

{
  "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"
    }
  ]
}

Required behavior

必需行为

Outer folder name and
```
plugin.json
```
```
"name"
```
are always the same normalized plugin name.
Do not remove required structure; keep
```
.codex-plugin/plugin.json
```
present.
Keep manifest values as placeholders until a human or follow-up step explicitly fills them.
If creating files inside an existing plugin path, use
```
--force
```
only when overwrite is intentional.
Preserve any existing marketplace
```
interface.displayName
```
.
When generating marketplace entries, always write
```
policy.installation
```
,
```
policy.authentication
```
, and
```
category
```
even if their values are defaults.
Add
```
policy.products
```
only when the user explicitly asks for that override.
Keep marketplace
```
source.path
```
relative to repo root as
```
./plugins/<plugin-name>
```
.

外层文件夹名称和
```
plugin.json
```
中的
```
"name"
```
始终为相同的标准化插件名。
不得移除必需结构；必须保留
```
.codex-plugin/plugin.json
```
文件。
清单值保留为占位符，直到人工或后续步骤明确填充。
如果要在现有插件路径下创建文件，仅当有意覆盖时才使用
```
--force
```
参数。
保留任何已有的市场
```
interface.displayName
```
值。
生成市场条目时，始终写入
```
policy.installation
```
、
```
policy.authentication
```
和
```
category
```
字段，即使它们的值是默认值。
仅当用户明确要求覆写时才添加
```
policy.products
```
字段。
市场的
```
source.path
```
始终保留为相对于仓库根目录的路径：
```
./plugins/<plugin-name>
```
。

Reference to exact spec sample

准确规范示例参考

For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:

```
references/plugin-json-spec.md
```

如需获取插件清单和市场条目的标准JSON示例，请查看：

```
references/plugin-json-spec.md
```

Validation

验证

After editing

SKILL.md

, run:

bash

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

编辑完

SKILL.md

后，运行：

bash

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