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>


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


For a home-local plugin, treat `<home>` as the root and use:

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

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


如果是用户本地目录下的插件，将`<home>`作为根目录，使用以下命令：

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

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

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会生成的内容

If the user has not made the plugin location explicit, ask whether they want a repo-local plugin or a home-local plugin before generating marketplace entries.

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

For a home-local plugin, use the same convention with
```
<home>
```
as the root:
```
~/.agents/plugins/marketplace.json
```
plus
```
./plugins/<plugin-name>
```
.
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

路径下。

对于用户目录本地插件，遵循相同的约定，将
```
<home>
```
作为根目录：
```
~/.agents/plugins/marketplace.json
```
和
```
./plugins/<plugin-name>
```
。
插件市场根元数据支持顶层
```
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