# How to Add Skills to a Plugin in OpenAI Plugins: A Complete Guide

> Learn how to add skills to your OpenAI plugin. This guide explains creating SKILL.md files for automatic discovery and registration within your plugin.

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

---

**You add skills to a plugin by creating a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file with YAML front-matter inside a `skills/<skill-name>/` directory within the plugin folder, which Codex automatically discovers and registers without requiring manual registration steps.**

Adding capabilities to an existing plugin in the OpenAI Plugins repository follows a convention-driven architecture that eliminates manual registration overhead. By placing a properly formatted [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file inside a dedicated skills directory, you enable the Codex runtime to automatically discover, parse, and expose new functionality to LLM agents.

## Understanding the Skill Directory Structure

The OpenAI Plugins repository uses a glob-based discovery system that scans for [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files under the pattern `plugins/**/skills/**/SKILL.md`. According to the source code in the repository, each skill resides in its own subdirectory under the parent plugin's `skills/` folder.

For example, the **Box** plugin (`plugins/box`) organizes skills as follows:

```text
plugins/box/skills/
└─ box/
   ├─ SKILL.md
   ├─ scripts/
   │   └─ box_rest.py
   └─ agents/
       └─ openai.yaml

```

This convention applies to all plugins. When Codex loads the plugin, it parses the YAML front-matter from each [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file and registers the skill automatically.

## Step-by-Step Guide to Adding a New Skill

Follow these steps to add a skill to any existing plugin in the repository.

### Create the Skill Directory

Navigate to the plugin you want to extend and create a new folder for your skill. For a plugin named `box` and a skill named `greet-user`, create:

```bash
mkdir -p plugins/box/skills/greet-user

```

### Define the SKILL.md Manifest

Create a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file inside the new skill directory. This file contains mandatory YAML front-matter that defines the skill's metadata, triggers, and execution path. Referencing the structure from [`plugins/box/skills/box/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/SKILL.md), your minimal [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) should include:

```yaml
---
name: greet-user
description: |
  Returns a friendly greeting for the supplied name.
triggers:
  - "greet me"
  - "say hello"
run: scripts/greet.py
output: text
required-files: []
---

```

The front-matter supports several key fields:

- **name** – Unique identifier for the skill
- **description** – Human-readable explanation of functionality
- **triggers** – Phrases that invoke the skill
- **run** – Relative path to the executable script
- **output** – Expected output format (e.g., `text`, `json`)
- **required-files** – Array of file paths the skill needs at runtime

### Add Execution Scripts

Create the script referenced in the `run` field. Following the pattern in [`plugins/box/skills/box/scripts/box_rest.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_rest.py), add a `scripts/` folder and your executable:

```python

# plugins/box/skills/greet-user/scripts/greet.py

import sys
import json

def main():
    # Expect a JSON payload like {"name": "Alice"}

    payload = json.load(sys.stdin)
    name = payload.get("name", "friend")
    print(f"Hello, {name}! 👋")

if __name__ == "__main__":
    main()

```

The script can be written in any language—Python, Node.js, or TypeScript—provided the `run` path in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) points to the correct executable.

### Add Supporting Assets (Optional)

You can include additional subdirectories for complex skills:

- **scripts/** – Executable code
- **agents/** – LLM agent definitions
- **references/** – Reference documentation or data files
- **assets/** – Binary assets or templates

Place these next to [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) as needed.

### Configure Agent Integration (Optional)

To enable LLM agents to invoke your skill, add an agent definition in an `agents/` subdirectory. Following the example in [`plugins/box/skills/box/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/agents/openai.yaml), create:

```yaml

# plugins/box/skills/greet-user/agents/openai.yaml

agents:
  - name: greet-agent
    description: |
      An OpenAI-compatible agent that calls the greet-user skill.
    steps:
      - call: greet-user
        input:
          name: "{{ user_name }}"
        output: greeting

```

### Update Plugin Permissions (Optional)

If your skill requires additional permissions (such as OAuth scopes), modify the plugin's manifest. As shown in [`plugins/fal/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/fal/.codex-plugin/plugin.json), edit the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file in the `.codex-plugin` directory:

```json
{
  "oauthScopes": [
    "read",
    "write"
  ]
}

```

## How Skill Discovery Works

The Codex platform implements zero-configuration skill registration. When the plugin loads, the runtime:

1. Glob-searches for `plugins/**/skills/**/SKILL.md` files
2. Parses the YAML front-matter from each file
3. Registers the skill using the `name` field as the identifier
4. Binds the triggers to the execution script specified in the `run` field

This eliminates the need for a central registry or manual registration steps. Skills are discovered solely from the file layout and front-matter content.

## Testing Your New Skill Locally

Validate your implementation using the Codex CLI from the repository root:

```bash

# Verify the skill appears in the registry

codex plugins list

# Execute the skill with test input

codex plugins run greet-user '{"name":"Bob"}'

```

Expected output:

```text
Hello, Bob! 👋

```

## Summary

- **Skills are self-contained units** added via convention-driven file placement in `plugins/<plugin-name>/skills/<skill-name>/`.
- **SKILL.md front-matter** defines the skill metadata, triggers, and execution path without requiring code changes to the plugin core.
- **Supporting assets** such as scripts, agents, references, and assets reside in subdirectories adjacent to [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md).
- **Automatic discovery** occurs through glob scanning—no manual registration is required.
- **Optional manifest updates** in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) are only needed when adding new OAuth scopes or runtime configurations.

## Frequently Asked Questions

### Can I use languages other than Python for skill scripts?

Yes. The `run` field in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) accepts any executable path. You can write scripts in Node.js, TypeScript, Ruby, or any language supported by the runtime environment, provided the script can read from STDIN and write to STDOUT.

### Do I need to restart the Codex runtime after adding a new skill?

No. The Codex platform scans for [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files dynamically. However, depending on your local development setup, you may need to reload the plugin or restart the CLI to pick up new files in some caching scenarios.

### Where can I find a template to scaffold a new skill quickly?

The repository includes a plugin-creator skill at [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) that can generate the skeleton for a new skill, including the directory structure and boilerplate [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) front-matter.

### How do I handle skill dependencies or external libraries?

Install dependencies at the plugin level or use a [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt) or [`package.json`](https://github.com/openai/plugins/blob/main/package.json) in the skill's directory. Ensure the execution environment has access to these dependencies, or bundle them with your script. The `box` plugin demonstrates this pattern with its REST client scripts in [`plugins/box/skills/box/scripts/box_rest.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_rest.py).