System Plugin Creator — Workflow

Overview

How the system-plugin-creator skill works, step by step.

Source Workflow

Codex skill workflow.

Step-by-step Workflow

Plugin Creator

Quick Start

Run the scaffold script:

  # 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 ~/plugins/<plugin-name>.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

Edit <plugin-path>/.codex-plugin/plugin.json when the request gives specific metadata. The scaffold starts with valid defaults and must not contain [TODO: ...] placeholders.
Generate or update the personal marketplace entry when the plugin should appear in Codex UI ordering:

# Personal marketplace entries default to ~/.agents/plugins/marketplace.json.
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace

Only use a repo/team marketplace when the user specifically asks for that destination:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.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> \
  --marketplace-path <marketplace-json-path> \
  --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).

Before handing back a generated plugin, run:

python3 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>

What this skill creates

Default marketplace-backed scaffolds are personal: ~/plugins/<plugin-name>/ plus ~/.agents/plugins/marketplace.json.
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 validated schema shape that the ingestion path accepts.
Creates or updates ~/.agents/plugins/marketplace.json when --with-marketplace is set.
- If the marketplace file does not exist yet, seed a personal marketplace root 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

Personal creation defaults to ~/.agents/plugins/marketplace.json.
Repo/team marketplace creation is opt-in through both --path and --marketplace-path, only when the user specifically requests it.
In either location, the generated source path remains ./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 the target marketplace file 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": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "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.
Do not leave [TODO: ...] placeholders in plugin manifests.
Keep apps and mcpServers out of plugin.json unless their companion files are actually created.
Omit unsupported plugin manifest fields that validation rejects, including hooks.
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 the selected marketplace root as ./plugins/<plugin-name>.
When the workflow created or updated a marketplace-backed plugin, end the final user-facing response with a short Codex app handoff. Say To view this in the Codex app: and write View <normalized plugin name> and Share <normalized plugin name> as Markdown links, not raw URLs or code spans.
The View deeplink uses codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>. The Share deeplink uses the same URL with &mode=share.
Replace the placeholders with the real normalized plugin name and absolute marketplace.json path from the scaffolded plugin. URL-encode the path segment and query value when needed.
Do not add pluginName or hostId query parameters to these deeplinks. Codex derives both after the user clicks the link.
Do not emit the View <normalized plugin name> or Share <normalized plugin name> links when no marketplace entry was created or updated.

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

Before handing back a generated plugin, run:

python3 .agents/skills/plugin-creator/scripts/validate_plugin.py <plugin-path>

Execution Logic

The skill executes when its trigger fires (slash command, natural-language match, or direct invocation). It reads its references, applies its rules, and produces the documented outputs.

Edge Cases

See the source skill's references/ and scripts/ folders for edge-case handling.

Failure Handling

A skill failure surfaces as a tool error or a partial output; never a silent skip. Re-run with --verbose (where applicable) for diagnostics.

Integration Notes

Claude — invoked via the Skill tool with skill: "system-plugin-creator".
Codex — referenced from AGENTS.md if mirrored.
Antigravity — referenced from the workspace agent rules if mirrored.
HQ Project — listed on the landing page Skills section + post-login sidebar.
MD Project (md.sgnk.ai) — file rendered from Skills/System Plugin Creator/workflow.md.
Obsidian — file rendered with frontmatter + tags.

Usage Examples

Invoke via slash command or natural language matching the skill description.

Source: (none)