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

You add skills to a plugin by creating a 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 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 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:

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 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:

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

Define the SKILL.md Manifest

Create a 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, your minimal SKILL.md should include:

---
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, add a scripts/ folder and your executable:

# 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 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 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, create:

# 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, edit the plugin.json file in the .codex-plugin directory:

{
  "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:

# 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:

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.
• Automatic discovery occurs through glob scanning—no manual registration is required.
• Optional manifest updates in .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 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 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 that can generate the skeleton for a new skill, including the directory structure and boilerplate SKILL.md front-matter.

How do I handle skill dependencies or external libraries?

Install dependencies at the plugin level or use a requirements.txt or 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.

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