How to Use the Plugin Creator Skill in Codex: Complete Scaffold Guide

The Plugin Creator skill automates the scaffolding of a new Codex plugin—including its manifest, optional resources (skills, hooks, scripts, assets, MCP, and App files), and optional marketplace registration.

The Plugin Creator skill in Codex serves as a thin wrapper around the Python script create_basic_plugin.py in the openai/plugins repository. When you invoke this skill from Codex or run the script directly, it validates your plugin name, creates the directory structure, and generates a complete plugin.json manifest. You can optionally register the plugin to a personal or team marketplace for easy sharing across your organization.

Core Workflow and Implementation

The skill delegates all heavy lifting to .agents/skills/plugin-creator/scripts/create_basic_plugin.py. Understanding the internal functions helps you customize the generated scaffold or debug issues.

Name Normalization and Validation

Before creating files, the script sanitizes your input through normalize_plugin_name (converting to lower-case with hyphen separation) and validates length constraints via validate_plugin_name. Invalid names trigger immediate errors before any filesystem changes occur.

Directory Structure Creation

The scaffolded plugin root defaults to ~/plugins/<plugin-name> unless you specify an alternate path with --path. The script calls plugin_root.mkdir at lines 51-53 to create this directory and any necessary parent folders.

Manifest Generation

At the heart of the skill lies build_plugin_json, which writes the .codex-plugin/plugin.json manifest. This JSON file contains the full manifest shape required by Codex, including metadata, entry points, and resource declarations.

Optional Resources and Marketplace Registration

Beyond the basic manifest, the skill can populate additional directories and register your plugin for discovery.

Creating Optional Resources

Pass any combination of flags to scaffold empty directories and stub files:

• --with-skills creates a skills/ directory
• --with-hooks creates a hooks/ directory
• --with-scripts creates a scripts/ directory
• --with-assets creates an assets/ directory
• --with-mcp creates a stub .mcp.json file
• --with-apps creates a stub .app.json file

Marketplace Configuration

When you supply --with-marketplace, the skill invokes update_marketplace_json to register your plugin.

Two marketplace locations are supported:

Personal marketplace: ~/.agents/plugins/marketplace.json (default).

Repository or team marketplace: <repo-root>/.agents/plugins/marketplace.json when using --marketplace-path.

Each entry includes required fields such as policy.installation, policy.authentication, and category, following the JSON schema documented in plugin-json-spec.md.

Command-Line Usage Examples

While primarily designed for Codex integration, you can invoke the skill directly via Python for CI/CD pipelines or local development.

Quick Scaffold

Create a personal plugin under the default ~/plugins/ directory:

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

Scaffold with Optional Resources

Generate a plugin with skills, hooks, assets, and MCP support:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-awesome-plugin \
  --with-skills \
  --with-hooks \
  --with-scripts \
  --with-assets \
  --with-mcp \
  --with-apps

Register to Personal Marketplace

Create a plugin and immediately add it to your personal marketplace:

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

Repository-Scoped Plugin with Team Marketplace

Target a specific directory and update the repo's marketplace file:

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

Force Overwrite Existing Entries

Use caution when updating existing plugins—this will overwrite marketplace entries and manifest files:

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

Safety Mechanisms and Idempotency

The Plugin Creator skill implements defensive checks to prevent accidental data loss.

The script refuses to overwrite an existing marketplace entry unless you explicitly pass --force. Similarly, both the manifest (plugin.json) and marketplace files are written via a write_json utility that checks for existence before writing. These protections ensure you cannot accidentally destroy working plugin configurations during iterative development.

After successful execution, the script prints the absolute paths to your scaffolded plugin directory, manifest file, and (if applicable) the updated marketplace file. When invoked from Codex, the final UI should present "View " and "Share " deep-links according to the skill specification, though the underlying script only outputs filesystem paths.

Summary

• The Plugin Creator skill wraps create_basic_plugin.py to automate Codex plugin scaffolding.
• It validates plugin names via normalize_plugin_name and validate_plugin_name before creating directories.
• The manifest at .codex-plugin/plugin.json is generated by build_plugin_json with full schema compliance.
• Optional flags create resources directories (skills, hooks, scripts, assets) and stub configuration files (MCP, Apps).
• Marketplace registration supports both personal (~/.agents/plugins/marketplace.json) and repository-scoped paths via --marketplace-path.
• The --force flag bypasses overwrite protection for idempotent updates to existing plugins.

Frequently Asked Questions

What is the default installation path for scaffolded plugins?

By default, the Plugin Creator skill installs new plugins to ~/plugins/<plugin-name>/. You can override this destination using the --path argument to specify any filesystem location or repository-relative directory.

Does the skill support updating existing plugins or only creating new ones?

The skill supports updating existing plugins, but only when you explicitly provide the --force flag. Without this flag, the script prevents overwriting existing manifest files and marketplace entries to protect against accidental configuration loss.

What marketplace fields are required when using --with-marketplace?

When registering to a marketplace, the entry must include policy.installation, policy.authentication, and category fields. These follow the canonical JSON schema defined in .agents/skills/plugin-creator/references/plugin-json-spec.md within the openai/plugins repository.

Can I use the Plugin Creator skill outside of the Codex interface?

Yes. While designed for Codex integration, the underlying create_basic_plugin.py script functions as a standalone Python CLI tool. You can invoke it directly in shell scripts, CI/CD pipelines, or local development workflows without launching the Codex agent.

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