Preface¶

A single Agent Skill is perfect for encapsulating “how to do one thing”: a SKILL.md, several scripts, and reference materials that an Agent can load on demand. However, once a team needs to distribute multiple Skills, connected MCPs, lifecycle hooks, and display resources together, relying on scattered directory copying becomes unstable. What we need is a packaged unit with a stable identity, installable, and capable of being displayed in the directory.

In the Codex / ChatGPT ecosystem, this unit is called a Plugin. OpenAI’s official built-in plugin-creator Skill is specifically designed to create and scaffold Plugin directories: it automatically generates the required .codex-plugin/plugin.json, fills in optional component placeholders as needed, and can write to local or repository-level marketplace.json to facilitate testing and distribution in the Plugins Directory.

This article is organized after cross-verifying with the original text of plugin-creator from the OpenAI official repository, the plugin.json specification examples, and the Build plugins documentation.

What It Is¶

plugin-creator is a system-level Agent Skill maintained by OpenAI (located at skills/.system/plugin-creator in the openai/skills repository). Skills under the .system directory are automatically installed with newer versions of Codex, and generally do not need to be manually copied.

According to the official description, its responsibilities are:
- Create and scaffold Plugin directories for Codex;
- Always generate the required manifest .codex-plugin/plugin.json (with complete schema shape and editable placeholders);
- Create optional structures such as skills/, hooks/, scripts/, assets/, .mcp.json, .app.json as needed;
- Generate or update .agents/plugins/marketplace.json at the repository root (or user home directory) when needed, to control the display order and availability metadata of plugins in the UI.

One-sentence positioning: Skill solves “how to do one thing”; Plugin solves “how to package, install, and distribute”; plugin-creator is responsible for building the skeleton of the latter from scratch.

Core Features and Highlights¶

Combining SKILL.md, the scaffolding script scripts/create_basic_plugin.py, and official build documentation, the verified capabilities are as follows.

Standardized Manifest Entry
The entry point for every Plugin is .codex-plugin/plugin.json. Only this manifest should be placed under .codex-plugin/; skills/, hooks/, assets/, .mcp.json, .app.json and other components should be placed in the Plugin root directory. The scaffolding will write the complete field shape (including the interface display block) according to the specification, making it easy for you to replace placeholder content later.
Name Normalization
The plugin name will be normalized to lowercase hyphenated form, with a maximum length of 64 characters. For example, My Plugin → my-plugin, and consecutive separators will be collapsed. The generated folder name must match the "name" field in plugin.json.
One-click Placeholders for Optional Components
Optional directories and files can be created via script parameters:
- --with-skills → skills/
- --with-hooks → hooks/
- --with-scripts → scripts/
- --with-assets → assets/
- --with-mcp → .mcp.json (initialized to {"mcpServers": {}})
- --with-apps → .app.json (initialized to {"apps": {}})
Marketplace Registration
Adding the --with-marketplace parameter will create or update marketplace.json. The default repository-level path is <repo-root>/.agents/plugins/marketplace.json; the personal-level common path is ~/.agents/plugins/marketplace.json. New entries default to:
- policy.installation: "AVAILABLE"
- policy.authentication: "ON_INSTALL"
- category: "Productivity"

The order of entries in plugins[] is the display order on the Codex side; new entries are appended to the end of the list by default.

Direct In-chat Invocation
The official build documentation states that you can use @plugin-creator in ChatGPT Work mode, and $plugin-creator in Codex. You do not need to write the directory manually first—just clearly state your requirements (including the MCP’s plugin_asdk_app... ID, whether you need a personal marketplace, etc.).

Installation and Activation¶

Using in Codex / ChatGPT (Recommended)¶

plugin-creator is a system Skill, and newer versions of Codex will include it automatically. The daily usage is to explicitly call it in a conversation:
- Codex: $plugin-creator
- ChatGPT (Work mode): @plugin-creator

The official example prompt (when testing a local plugin with MCP) is similar to:

@plugin-creator create a plugin for ChatGPT and Codex using my MCP server.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.

After generation, verify according to the documentation: whether .app.json points to the correct plugin_asdk_app... ID; whether the apps field in .codex-plugin/plugin.json points to ./.app.json; supplement SKILL.md under skills/ when reusable workflows are needed.

Running the Scaffolding Script Directly¶

If you already have the Skill directory locally (for example, installed to .agents/skills/plugin-creator with Codex, or checked out from the official repository), you can also execute the script directly. The repository version defaults to creating plugins/<plugin-name> in the current repository:

# The plugin name will be normalized to lowercase hyphens and <= 64 characters
# Default output to <repo_root>/plugins/<plugin-name>
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>

Open the generated .codex-plugin/plugin.json and replace the [TODO: ...] placeholders with real metadata.

To write to the marketplace at the same time:

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

For local plugins in your home directory, you can explicitly specify the path:

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

To populate all commonly used optional structures at once:

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

Use --force only when overwriting existing files or duplicate marketplace entries to avoid accidental overwrites.

About Other AI Programming Tools¶

plugin-creator itself follows the standard SKILL.md format, so Cursor, Claude Code, and other tools can also read it and execute the scaffolding logic as instructed. However, the generated Plugin package (.codex-plugin/plugin.json + marketplace) is targeted at the Codex / ChatGPT Plugins Directory; in other tools, you should understand it as “scaffolding a directory according to the OpenAI Plugin specification”, rather than being equivalent to each tool’s own extension marketplace.

Supplement: The README of the openai/skills repository has prompted that examples and documentation are migrating to openai/plugins and Build plugins; the calling method of system Skills still refers to the built-in $plugin-creator / @plugin-creator in Codex / ChatGPT.

Typical Usage Examples¶

1. Minimal Viable Plugin Structure (Manual Comparison)¶

The minimal form given in the official documentation matches the scaffolding target:

mkdir -p my-first-plugin/.codex-plugin
mkdir -p my-first-plugin/skills/hello

.codex-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

skills/hello/SKILL.md:

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

Then use @plugin-creator or manual editing to register this plugin into the marketplace.

2. Marketplace Entry Shape¶

The plugin entry written by the scaffolding looks like:

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

A brand new marketplace file will also include root-level metadata:

{
  "name": "[TODO: marketplace-name]",
  "interface": {
    "displayName": "[TODO: Marketplace Display Name]"
  },
  "plugins": []
}

Note: displayName belongs to the interface at the marketplace root level, do not write it into individual plugins[] entries. source.path is resolved relative to the marketplace root directory (not relative to the .agents/plugins/ folder itself).

Allowed values for policy fields (from the original Skill text):
- policy.installation: NOT_AVAILABLE | AVAILABLE | INSTALLED_BY_DEFAULT
- policy.authentication: ON_INSTALL | ON_USE
- policy.products should only be written when explicitly required for product gating.

3. Common Fields in `plugin.json`¶

In the specification example (references/plugin-json-spec.md), in addition to basic identity fields, common ones include:
- skills / hooks / mcpServers / apps: Relative paths, it is recommended to start with ./;
- interface.displayName, shortDescription, longDescription: Displayed in the directory and detail page;
- interface.defaultPrompt: Up to 3 entries, each entry is recommended to be about 50 characters, with a maximum of 128 characters;
- Icon, screenshot and other resource paths under interface, screenshots must be in PNG format and placed in ./assets/.

Path fields are “supplements to the default discovery” and will not replace the default component discovery rules.

4. Managing Marketplace Sources via CLI¶

The official documentation also provides marketplace management commands (complementary to the scaffolding) that do not require manual configuration edits:

codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

After modifying a local plugin, you usually need to restart the ChatGPT desktop app or follow the refresh process of your current environment to see the updates in the Plugins Directory.

Applicable Scenarios and Notes¶

Suitable For:¶

Packaging multiple Skills, MCPs, and hooks into “installable packages” for team reuse;
Maintaining .agents/plugins/marketplace.json in the repository to unify the plugin list for colleagues;
Testing plugins locally on your own machine before deciding whether to publish to the public Plugin Directory;
Having an existing MCP connection (including the plugin_asdk_app... ID) and needing to quickly connect it into a Plugin.

Notes During Use:¶

Clarify the Deployment Target First: When the Skill’s required location is unclear, confirm whether it is an in-repository plugin or a home directory plugin first, then write the marketplace configuration.
Do Not Treat Placeholders as Final Content: The repository version scaffolding will leave [TODO: ...] placeholders, which must be replaced with real metadata before publishing or formal testing.
Directory Convention: Only plugin.json should be placed in .codex-plugin/; all other components go in the plugin root directory.
Use --force Cautiously: Only use it when overwriting existing manifests or duplicate marketplace entries.
Personal Directory Examples Are Not Unique: Documentation examples often use ~/.codex/plugins/, while the Skill script examples often use ~/plugins/; what really takes effect is the resolution result of source.path relative to the marketplace root, just keep the two aligned.
Public Distribution Has Separate Processes: Local / repository marketplaces are mainly used for creation, testing, and internal team distribution; publishing to the general plugin directory requires following the subsequent steps of the official Build plugins documentation, which are not covered in this article for unconfirmed details.

Summary¶

plugin-creator turns Codex Plugin development from “remembering a bunch of directory conventions” into “building the skeleton with one command or one conversation”. For developers who already know how to write Skills, it is the standard next step towards installable, sortable, and team-distributable packages; for people new to Plugins, it is also the fastest entry point to compare against the official specifications.

Official Skill Repository:
https://github.com/openai/skills/tree/main/skills/.system/plugin-creator

Build and Packaging Documentation:
https://developers.openai.com/codex/plugins/build

Skills Overview:
https://developers.openai.com/codex/skills

plugin-creator: One-click Scaffold Codex Plugin with Official Skill

Preface¶

What It Is¶

Core Features and Highlights¶

Installation and Activation¶

Using in Codex / ChatGPT (Recommended)¶

Running the Scaffolding Script Directly¶

About Other AI Programming Tools¶

Typical Usage Examples¶

1. Minimal Viable Plugin Structure (Manual Comparison)¶

2. Marketplace Entry Shape¶

3. Common Fields in `plugin.json`¶

4. Managing Marketplace Sources via CLI¶

Applicable Scenarios and Notes¶

Suitable For:¶

Notes During Use:¶

Summary¶

Tags

Preface¶

What It Is¶

Core Features and Highlights¶

Installation and Activation¶

Using in Codex / ChatGPT (Recommended)¶

Running the Scaffolding Script Directly¶

About Other AI Programming Tools¶

Typical Usage Examples¶

1. Minimal Viable Plugin Structure (Manual Comparison)¶

2. Marketplace Entry Shape¶

3. Common Fields in plugin.json¶

4. Managing Marketplace Sources via CLI¶

Applicable Scenarios and Notes¶

Suitable For:¶

Notes During Use:¶

Summary¶

Tags

3. Common Fields in `plugin.json`¶