# How to Define and Configure Skills for a Codex Plugin: A Complete Guide > Learn to define and configure skills for a Codex plugin using SKILL.md and openai.yaml files. This guide explains how LLMs leverage these components for enhanced functionality. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-07 --- **A skill in the Codex ecosystem is a reusable capability defined by a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file with YAML front-matter and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) front-matter to register the skill's metadata, and loads the associated agent configuration from [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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: ```text plugin-root/ └─ skills/ └─ / ├─ 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md), the minimal structure requires: ```yaml --- 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`: ```yaml 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) (metadata and documentation) and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) (LLM configuration) to function within the Codex ecosystem. - Place skills in the `skills//` directory with optional `assets/`, `scripts/`, or `hooks/` subdirectories for auxiliary files. - The front-matter in [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) with valid YAML front-matter containing `name` and `description` fields, and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.