How to Add Skills to an Existing Codex Plugin: The Complete Developer Guide

To add skills to an existing Codex plugin, create a subdirectory under skills/ containing a SKILL.md file with YAML front-matter and an agents/openai.yaml configuration, then populate any optional asset or script folders required by the capability.

The OpenAI Codex ecosystem treats skills as modular, reusable capabilities that extend plugin functionality through declarative configuration. When you add skills to an existing Codex plugin in the openai/plugins repository, you create self-contained units that the LLM automatically discovers and invokes at runtime. Each skill follows a strict directory convention that separates human-readable documentation from machine-readable agent configurations.

Understanding the Skill Architecture

A skill is a reusable building block that describes a specific capability—such as handling Zoom webhooks or fetching Zotero references—within the Codex framework. According to the openai/plugins source code, every skill resides in a dedicated folder under the plugin's skills/ directory and consists of three distinct parts: a metadata specification, an agent configuration, and optional resource files.

When Codex loads a plugin, it recursively scans every skills/* folder, parses the SKILL.md front-matter, and registers the associated agent from agents/openai.yaml. This registration process makes the skill available for invocation by users or other plugin components through the Codex UI.

plugin-root/
└─ skills/
   └─ <skill-name>/
      ├─ SKILL.md               ← human-readable spec
      ├─ agents/
      │   └─ openai.yaml         ← LLM agent definition
      ├─ assets/ (optional)      ← icons, images, etc.
      ├─ scripts/ (optional)     ← helper scripts
      └─ hooks/ (optional)       ← server-side webhook handlers

The Three Core Components

Every skill you add to a Codex plugin requires two mandatory files and supports several optional resource directories.

SKILL.md

The SKILL.md file serves as the skill's manifest and documentation. It must contain a YAML front-matter block defining the name and description fields, followed by markdown content explaining the workflow, required inputs, and reference links.

The front-matter metadata controls how the skill appears in the Codex UI, while the body content provides context for developers and the LLM.

agents/openai.yaml

This YAML file declares the LLM agent configuration, specifying how the model behaves when the skill is invoked. Critical configuration keys include:

• system: The system prompt defining the agent's role
• temperature: Sampling temperature for response generation
• tools: Available tool integrations
• max_tokens: Response length limits

Optional Resources

Skills can include supplementary folders that provide static assets or executable logic:

• assets/: Icons, images, or other static files referenced by the skill
• scripts/: Helper scripts for data processing or API interactions
• hooks/: Server-side webhook handlers for external service integration

Step-by-Step Implementation

To add a new skill to an existing Codex plugin, follow this implementation pattern:

1. Create the skill directory under skills/<skill-name>/ in your plugin root.

2. Add SKILL.md with valid YAML front-matter containing name and description fields, followed by workflow documentation.

3. Create agents/openai.yaml to specify LLM behavior, including system prompts and tool configurations.

4. Include auxiliary files such as webhook verification scripts in hooks/ or static assets in assets/ if the skill requires external integrations.

When the plugin is built or loaded in the Codex UI, the new skill appears automatically in the available capabilities list.

Complete Working Examples

The following examples demonstrate a minimal skill implementation that greets users.

Minimal SKILL.md:

---
name: my-sample-skill
description: Demonstrates a basic skill that greets the user.
---

# My Sample Skill

Use this skill when you need a friendly greeting. It does not require any external APIs.

## Workflow

1. Receive the user's name as an input.
2. Return a personalized greeting string.

## References

- None

Corresponding agents/openai.yaml:

system: |
  You are a helpful assistant that generates friendly greetings.
temperature: 0.3
max_tokens: 50
tools: []

Resulting folder structure:

my-plugin/
└─ skills/
   └─ greet-user/
      ├─ SKILL.md          ← metadata and documentation
      └─ agents/
          └─ openai.yaml   ← LLM configuration

Key Reference Files in the Repository

The openai/plugins repository provides canonical templates and concrete implementations for skill development:

• .agents/skills/plugin-creator/SKILL.md: Contains the official template for skill definitions, showing required front-matter fields and documentation standards.

• .agents/skills/plugin-creator/agents/openai.yaml: Provides the base YAML structure for agent configuration, demonstrating proper syntax for system prompts and parameter definitions.

• plugins/zoom/skills/webhooks/SKILL.md: A production-ready example showing how to structure skills that handle external webhooks, including references to helper documentation and integration patterns.

Summary

• Skills extend Codex plugin functionality through modular, reusable capabilities defined in the skills/ directory.
• Every skill requires SKILL.md (with YAML front-matter for name and description) and agents/openai.yaml (defining LLM behavior).
• Optional folders (assets/, scripts/, hooks/) support additional resources and server-side logic.
• Codex automatically discovers and registers skills at runtime by scanning the skills/ directory and parsing configuration files.
• The openai/plugins repository provides templates at .agents/skills/plugin-creator/ and real-world examples like plugins/zoom/skills/webhooks/.

Frequently Asked Questions

What is the minimum file structure required to add a skill to an existing Codex plugin?

You must create a folder under skills/<skill-name>/ containing at least two files: SKILL.md with valid YAML front-matter (including name and description fields) and agents/openai.yaml with the LLM configuration. Without both files, Codex will not register the skill in the UI.

How does Codex discover newly added skills in a plugin?

Codex recursively scans the skills/ directory at plugin load time, parsing the front-matter of each SKILL.md file to extract metadata and loading the corresponding agent configuration from agents/openai.yaml. This happens automatically when the plugin is built or run in the Codex UI, requiring no manual registration steps.

Can I include custom scripts or assets when adding a skill to a Codex plugin?

Yes. The skill architecture supports optional scripts/ folders for helper utilities, assets/ folders for static files like icons, and hooks/ folders for server-side webhook handlers. These resources are referenced relative to the skill directory and loaded when the skill is invoked.

What parameters must be defined in the agents/openai.yaml file?

At minimum, you should define the system prompt to specify the agent's behavior. Common parameters include temperature (controlling response randomness), max_tokens (limiting output length), and tools (listing available external tools). The exact requirements depend on how the LLM needs to interact with the skill's specific capability.

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