# How to Use the plugin-creator Skill to Scaffold New OpenAI Plugins

> Learn to scaffold new OpenAI plugins using the plugin-creator skill. Generate validated plugin directories and starter plugin.json files quickly.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-10

---

**The plugin-creator skill provides a Python CLI tool in `.agents/skills/plugin-creator` that generates validated plugin directories with starter [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) files and optional Marketplace registration.**

The OpenAI plugins repository includes a hidden **plugin-creator skill** designed to accelerate plugin development. Located in the `.agents/skills/plugin-creator` package, this utility automates the boilerplate required for new plugin scaffolding. By leveraging the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script, developers can generate properly structured plugin directories without manual configuration.

## Where the plugin-creator Skill Lives

The skill resides in a hidden directory structure within the repository root. Its core implementation lives in [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py), which handles all scaffolding logic including argument parsing, validation, and file generation.

The skill exposes its metadata to the agent framework through [`.agents/skills/plugin-creator/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/agents/openai.yaml). This YAML file declares the default prompt, description, and other configuration data that LLMs use when interacting with the skill.

Documentation for end users is maintained in [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md), which contains detailed usage examples and flag descriptions.

## How the Scaffolding Works

When you invoke the plugin-creator skill, the [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script executes a five-stage pipeline:

### 1. CLI Argument Parsing

The script uses Python's `argparse` module to process command-line inputs. It accepts the plugin name as a positional argument, plus optional flags like `--with-marketplace`, `--plugin-dir`, `--install-policy`, and `--auth-policy`.

### 2. Name Normalization and Validation

Before creating files, the script calls `normalize_plugin_name` and `validate_plugin_name` to ensure the supplied name meets length and character constraints. This validation prevents invalid filesystem characters and ensures compatibility with the plugin registry.

### 3. Directory and File Generation

The script creates a new directory under the default parent path `~/plugins` (or a user-specified location via `--plugin-dir`). It then writes a starter [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file populated by the `build_plugin_json` function, which structures the manifest according to OpenAI's plugin specifications.

### 4. Optional Marketplace Integration

When you pass the `--with-marketplace` flag, the script invokes `build_marketplace_entry` to generate a Marketplace entry. This entry merges into the user's `~/.agents/plugins/marketplace.json` file, defined by the `DEFAULT_MARKETPLACE_PATH` constant, making the plugin discoverable in the UI.

### 5. File Writing and Confirmation

Finally, the script writes all files to disk and prints a success message confirming the plugin location and Marketplace status.

## Running the plugin-creator Skill

Execute the Python script directly from the repository root to scaffold a new plugin. Here are the most common usage patterns:

Create a basic plugin scaffold with a placeholder [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json):

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-awesome-plugin

```

Scaffold and simultaneously register the plugin in the Marketplace:

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

```

Use custom policies and specify a non-default output directory:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
    my-awesome-plugin \
    --plugin-dir ~/my-plugins \
    --install-policy AVAILABLE \
    --auth-policy ON_INSTALL \
    --category Productivity \
    --with-marketplace

```

## Summary

- The **plugin-creator skill** lives in `.agents/skills/plugin-creator` and provides automated scaffolding through [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py).
- The script validates plugin names using `normalize_plugin_name` and `validate_plugin_name` to enforce filesystem and registry compatibility.
- By default, new plugins are created under `~/plugins` with a generated [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file constructed by `build_plugin_json`.
- The `--with-marketplace` flag triggers `build_marketplace_entry` to register the plugin in `~/.agents/plugins/marketplace.json`.
- Skill metadata is defined in [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) and documented in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) for agent framework integration.

## Frequently Asked Questions

### How do I install the plugin-creator skill?

The plugin-creator skill is bundled with the OpenAI plugins repository and requires no separate installation. Simply clone the repository and run the Python script located at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) using Python 3.

### What validation rules apply to plugin names?

The script enforces character and length constraints through `validate_plugin_name` and `normalize_plugin_name` functions defined in [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py). These rules ensure the name contains valid filesystem characters and meets OpenAI's plugin registry requirements, though specific regex patterns are implementation details within the validation functions.

### Can I change the default output directory for new plugins?

Yes. Use the `--plugin-dir` flag followed by your desired path. If omitted, the skill defaults to creating plugins under `~/plugins`. The script will create the directory structure recursively if it does not exist.

### What is the difference between basic scaffolding and Marketplace registration?

Basic scaffolding creates only the local plugin directory and [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file. Adding the `--with-marketplace` flag additionally calls `build_marketplace_entry` to insert a reference into `~/.agents/plugins/marketplace.json`, which makes the plugin visible in the OpenAI agent's plugin UI without requiring manual JSON editing.