How to Define and Configure Skills for a Codex Plugin: A Complete Guide

A skill in the Codex ecosystem is a reusable capability defined by a SKILL.md file with YAML front-matter and an agents/openai.yaml configuration that tells the LLM how to behave, living inside a plugin's skills/ directory.

When building extensions for the OpenAI Codex CLI, you must define and configure skills for a Codex plugin to expose specific capabilities like handling Zoom webhooks or fetching external data. According to the openai/plugins source code, each skill resides in its own subdirectory under skills/ and combines declarative metadata with LLM agent configuration to create discrete, invocable units of functionality.

What Is a Skill?

A skill is a discrete, reusable building block that encapsulates a specific capability of your plugin. Each skill functions as an independent agent that Codex can invoke based on user intent or programmatic triggers.

When Codex loads a plugin, it scans every skills/* folder, parses the SKILL.md front-matter to register the skill's metadata, and loads the associated agent configuration from agents/openai.yaml to determine how the LLM should behave when the skill is activated.

Skill Directory Structure

The filesystem layout follows a strict convention enforced by the Codex plugin loader:

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

How to Define and Configure a Skill

Step 1: Create the Skill Directory

Create a new folder under the plugin's skills/ directory using a descriptive kebab-case name. This folder will contain all files related to that specific capability.

Step 2: Configure SKILL.md with Front-Matter

The SKILL.md file serves as the human-readable specification and entry point. Its YAML front-matter defines the name and description that appear in the Codex UI, while the markdown body documents the workflow and references.

As implemented in .agents/skills/plugin-creator/SKILL.md, the minimal structure requires:

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

Step 3: Define Agent Behavior in agents/openai.yaml

This YAML file configures the LLM agent's system prompt, temperature, and available tools. According to the plugin specification, it typically contains keys like system, temperature, tools, and max_tokens:

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

Step 4: Add Optional Resources

Include helper scripts in scripts/, webhook handlers in hooks/, or static assets in assets/ as needed by your skill's workflow. Codex loads these resources relative to the skill's root when the skill is invoked.

Real-World Examples from openai/plugins

Template Reference

The canonical template resides at .agents/skills/plugin-creator/SKILL.md in the repository. This file establishes the required front-matter fields and markdown structure that all skills must follow, serving as the authoritative reference for skill definition syntax.

Production Implementation

For a concrete implementation, examine plugins/zoom/skills/webhooks/SKILL.md, which demonstrates handling Zoom webhooks with references to helper documentation and specialized configuration in its adjacent agents/openai.yaml. This example shows how to structure workflow documentation for complex API interactions and where to place webhook verification logic within the hooks/ subdirectory.

Summary

• A skill requires both SKILL.md (metadata and documentation) and agents/openai.yaml (LLM configuration) to function within the Codex ecosystem.
• Place skills in the skills/<skill-name>/ directory with optional assets/, scripts/, or hooks/ subdirectories for auxiliary files.
• The front-matter in SKILL.md must include name and description keys for registration in the Codex UI.
• Codex automatically discovers and registers skills by scanning the skills/ directory at plugin load time, requiring no manual registration steps.

Frequently Asked Questions

What files are required to create a minimal Codex skill?

At minimum, you need SKILL.md with valid YAML front-matter containing name and description fields, and an agents/openai.yaml file containing at least a system prompt. These two files define the skill's identity and LLM behavior respectively, allowing Codex to display and execute the capability.

Where should I put helper scripts for my skill?

Place auxiliary scripts in a scripts/ subdirectory within your skill folder. For webhook handlers or server-side logic, use the hooks/ directory. The Codex loader references these paths relative to the skill root when the skill is invoked, keeping all related capabilities organized under a single directory.

How does Codex know when to invoke a specific skill?

Codex parses the description field from each skill's SKILL.md front-matter to understand when to activate it. The system matches user intent against these descriptions and the system prompt defined in agents/openai.yaml to determine the appropriate skill to invoke during conversation flow.

Can I configure temperature and token limits for a skill?

Yes. Set temperature and max_tokens keys in the agents/openai.yaml file. These parameters control the LLM's creativity and response length when executing the specific skill, allowing fine-tuned behavior distinct from other skills in your plugin.

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