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

> Learn how to bundle multiple skills into a single OpenAI plugin. This guide covers organizing your project, creating skill files, and configuring your plugin.json for enhanced functionality.

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

---

**To bundle multiple skills into a single OpenAI plugin, create a `skills/` directory containing one sub-folder per capability, add a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file to each sub-folder, and set the `"skills"` field in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file, specify the path to your skills directory. Use a relative path to enable the auto-discovery mechanism:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/SKILL.md) file describing its purpose, inputs, outputs, and implementation. For the inspector skill at [`skills/inspect-design/SKILL.md`](https://github.com/openai/plugins/blob/main/skills/inspect-design/SKILL.md):

```markdown

# 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`](https://github.com/openai/plugins/blob/main/skills/generate-component/SKILL.md):

```markdown

# 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`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json) points to a `skills/` directory containing multiple independent capabilities:

- [`plugins/figma/skills/figma-use/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-use/SKILL.md) implements file utilization workflows
- [`plugins/figma/skills/figma-generate-design/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-generate-design/SKILL.md) handles design generation
- [`plugins/figma/skills/figma-implement-motion/SKILL.md`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).

## Verifying Your Skill Bundle

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

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json).
- **Define each skill** with a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file describing inputs, outputs, and implementation details.
- **Reference production examples** in [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file within each folder to determine the skill's interface. Each folder must contain exactly one [`SKILL.md`](https://github.com/openai/plugins/blob/main/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.