How to Bundle Multiple Skills into a Single OpenAI Plugin: Complete Guide

To bundle multiple skills into a single OpenAI plugin, create a skills/ directory containing one sub-folder per capability, add a SKILL.md file to each sub-folder, and set the "skills" field in .codex-plugin/plugin.json to point to that directory.

The openai/plugins repository implements a modular architecture that allows developers to ship cohesive, multi-capability tools without maintaining separate plugin packages. By leveraging the runtime's auto-discovery mechanism, you can group related functionalities—such as design inspection and code generation—into one unified plugin that the platform registers as multiple independent skills.

How the Multi-Skill Architecture Works

According to the source code in the openai/plugins repository, the plugin loader interprets the skills field in the manifest as either a single skill definition or a directory path. When configured as a directory, the runtime recursively walks the folder tree, parses each SKILL.md file encountered, and registers the containing folder as an independent skill.

This approach is implemented in the official Figma plugin, where the manifest at plugins/figma/.codex-plugin/plugin.json references a single skills/ directory that contains dozens of distinct capabilities, from figma-use to figma-generate-design. The runtime automatically discovers and loads every sub-folder without requiring explicit per-skill configuration.

Step-by-Step Implementation Guide

1. Configure the Plugin Manifest

In your .codex-plugin/plugin.json file, specify the path to your skills directory. Use a relative path to enable the auto-discovery mechanism:

{
  "name": "my-design-plugin",
  "version": "1.0.0",
  "description": "Design-to-code workflows",
  "skills": "./skills/",
  "interface": {
    "displayName": "My Design Plugin",
    "shortDescription": "Inspect designs and generate components",
    "capabilities": ["Read", "Write"]
  }
}

The "skills": "./skills/" entry instructs the platform to treat every immediate sub-directory within skills/ as a distinct, self-contained capability.

2. Create the Directory Structure

Create a skills/ directory in your plugin root, then add one sub-folder per skill. For example, to bundle an inspector and a generator:

my-design-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    ├── inspect-design/
    │   ├── SKILL.md
    │   └── inspect.py
    └── generate-component/
        ├── SKILL.md
        └── generate.js

3. Define Individual Skills

Each skill requires a SKILL.md file describing its purpose, inputs, outputs, and implementation. For the inspector skill at skills/inspect-design/SKILL.md:

# Inspect Design Skill

**Purpose**: Load a Figma file, extract component hierarchy, and return a JSON representation.

**Inputs**
- `fileId` (string): Figma file identifier.

**Outputs**
- `components` (array): List of component objects.

**Implementation**: Python script `inspect.py` that calls the Figma API.

For the generator skill at skills/generate-component/SKILL.md:

# Generate Component Skill

**Purpose**: Transform a component description into a React component file.

**Inputs**
- `componentSpec` (object): Name, props, and style information.

**Outputs**
- `code` (string): The generated component source.

**Implementation**: Node script `generate.js` that uses a template engine.

Real-World Reference from the OpenAI Plugins Repository

The production Figma plugin demonstrates this bundling pattern at scale. Its manifest at plugins/figma/.codex-plugin/plugin.json points to a skills/ directory containing multiple independent capabilities:

• plugins/figma/skills/figma-use/SKILL.md implements file utilization workflows
• plugins/figma/skills/figma-generate-design/SKILL.md handles design generation
• plugins/figma/skills/figma-implement-motion/SKILL.md manages animation implementation

The runtime discovers these skills automatically, proving that bundling multiple capabilities into a single OpenAI plugin is the standard, supported workflow.

Adding a New Skill to an Existing Plugin

To extend an existing plugin without modifying the manifest, create the skill directory and definition file:

mkdir -p skills/new-feature
cat > skills/new-feature/SKILL.md <<'EOF'

# New Feature Skill

Purpose: Describe the new capability.
Inputs: …
Outputs: …
EOF

cat > skills/new-feature/run.py <<'EOF'
import json, sys
def main():
    payload = json.load(sys.stdin)
    # ... perform work ...

    print(json.dumps({"result": "ok"}))
if __name__ == "__main__":
    main()
EOF

The plugin loader detects new-feature immediately on next initialization, requiring no changes to .codex-plugin/plugin.json.

Verifying Your Skill Bundle

If you have access to the Plugin-Eval CLI, validate the bundle before deployment:

plugin-eval list-skills --plugin-path ./my-design-plugin

This command enumerates every discovered skill, confirming that capabilities like inspect-design and generate-component are both active within your single plugin package.

Summary

• Bundle multiple skills by creating a skills/ directory and adding one sub-folder per capability.
• Configure auto-discovery by setting "skills": "./skills/" in .codex-plugin/plugin.json.
• Define each skill with a SKILL.md file describing inputs, outputs, and implementation details.
• Reference production examples in plugins/figma/.codex-plugin/plugin.json and its skills/ subdirectories.
• Add skills dynamically without modifying the manifest; the runtime discovers new sub-folders automatically.

Frequently Asked Questions

Can I mix different programming languages in the same plugin?

Yes. Each skill is self-contained and can use its own implementation language. For example, skills/data-processing/ might use Python while skills/ui-generation/ uses JavaScript. The plugin runtime invokes each skill independently based on the SKILL.md definition, regardless of the underlying language.

Do I need to update plugin.json when adding new skills?

No. Once the "skills" field points to a directory, the loader recursively discovers new sub-folders automatically. You only need to create the skill directory and its SKILL.md file. This design simplifies CI/CD pipelines, allowing you to add capabilities without re-registering the plugin.

How does the runtime differentiate between skills in the same directory?

The runtime uses the sub-folder name as the skill identifier and parses the SKILL.md file within each folder to determine the skill's interface. Each folder must contain exactly one SKILL.md describing that specific capability. Nested directories are treated as separate skill containers.

Is there a limit to how many skills I can bundle?

The openai/plugins repository does not specify a hard limit. The Figma plugin demonstrates production usage with dozens of skills in a single skills/ directory. Performance depends on the complexity of individual skill implementations and initialization time rather than the quantity of skills registered.

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