plugin-creator

$27

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

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:

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

What this skill creates

• 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

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:

{

  "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:

{

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

Reference to exact spec sample

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

• references/plugin-json-spec.md

Validation

After editing SKILL.md, run:

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