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

The plugin-creator skill provides a Python CLI tool in .agents/skills/plugin-creator that generates validated plugin directories with starter 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 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, 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. 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, which contains detailed usage examples and flag descriptions.

How the Scaffolding Works

When you invoke the plugin-creator skill, the 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 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:

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

Scaffold and simultaneously register the plugin in the Marketplace:

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:

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.
• 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 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 and documented in 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}