# How to Define and Configure Skills for a Codex Plugin: A Complete Guide > Learn to define and configure skills for a Codex plugin with this comprehensive guide. Master SKILL.md and openai.yaml for powerful plugin capabilities. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-12 --- **A skill in the Codex ecosystem is a reusable capability defined by a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) specification and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) configuration file within your plugin's `skills/` directory.** The openai/plugins repository provides the framework for building AI-powered extensions. Understanding how to define and configure skills for a Codex plugin is essential for creating modular capabilities that the Codex agent can discover and execute automatically. ## What Is a Codex Skill? A **skill** is a reusable building block that describes a specific capability of a plugin, such as handling Zoom webhooks or fetching Zotero references. Each skill lives inside a plugin's `skills/` directory and functions as an independent unit that Codex scans, parses, and registers at runtime. When loaded, the skill becomes available in the Codex UI and can be triggered by user requests or other plugin components. ## Required File Structure for Codex Skills Every skill follows a strict three-part structure. According to the template in [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md), you must provide specific files for Codex to recognize and load your skill. ### SKILL.md - The Skill Specification The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file serves as the human-readable contract and metadata source. It contains YAML front-matter that defines the skill's identity, followed by markdown documentation describing the workflow and references. The front-matter requires two fields: - `name`: The unique identifier for the skill - `description`: A short summary displayed in the Codex UI The body should detail the workflow, required inputs, and any external references. ```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 ``` ### agents/openai.yaml - The LLM Configuration The [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file declares how the Codex model should behave when executing this skill. This configuration tells the LLM how to act, what tools to use, and how to constrain its output. Typical keys include: - `system`: The system prompt defining the agent's persona and constraints - `temperature`: Sampling temperature (e.g., 0.3 for deterministic responses) - `tools`: Array of available tools the skill can invoke - `max_tokens`: Maximum tokens to generate in the response ```yaml system: | You are a helpful assistant that generates friendly greetings. temperature: 0.3 max_tokens: 50 tools: [] ``` ### Optional Resource Directories Skills may include additional folders for supporting assets: - `assets/`: Static files like icons and images referenced by the skill - `scripts/`: Helper scripts for data processing or API calls - `hooks/`: Server-side webhook handlers for external integrations ## Step-by-Step Guide to Creating a Skill Follow these steps to define and configure a new Codex skill: 1. Create a directory under `skills//` in your plugin root. 2. Add [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) with YAML front-matter specifying `name` and `description`. 3. Document the workflow, inputs, and external dependencies in the markdown body. 4. Create [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) to configure the LLM behavior, system prompt, and available tools. 5. Add auxiliary files to `assets/`, `scripts/`, or `hooks/` as needed for your implementation. When the plugin initializes, Codex automatically scans the `skills/` directory, parses each [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) front-matter, and registers the associated agent configurations. ```text my-plugin/ └─ skills/ └─ greet-user/ ├─ SKILL.md ← Skill specification └─ agents/ └─ openai.yaml ← LLM configuration ``` ## Real-World Examples from the openai/plugins Repository The repository provides canonical templates and production implementations. The [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) file demonstrates the required layout and fields for any new skill. For a concrete example, examine [`plugins/zoom/skills/webhooks/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/SKILL.md), which shows how to handle Zoom webhooks with proper documentation, workflow descriptions, and references to helper utilities. ## Summary - Skills reside in the `skills//` directory within your plugin root. - Each skill requires a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file with YAML front-matter defining `name` and `description`. - The [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file configures the LLM system prompt, temperature, tools, and token limits. - Optional directories (`assets/`, `scripts/`, `hooks/`) support additional functionality and server-side logic. - Codex automatically scans and registers skills when loading the plugin from the openai/plugins repository structure. ## Frequently Asked Questions ### What is the minimum required configuration for a Codex skill? You need two files: a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) with YAML front-matter containing `name` and `description` fields, and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) with at minimum a `system` prompt defining the agent's behavior. These files must reside in a subdirectory under `skills/` in your plugin root. ### How do I configure the LLM behavior for my skill? Configure the LLM through the [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file. Set the `system` key to define the agent's persona and instructions, adjust `temperature` to control creativity (use lower values for deterministic responses), and specify `max_tokens` to limit response length. You can also declare available `tools` for the skill to invoke during execution. ### Can I include server-side logic in a Codex skill? Yes. Create a `hooks/` directory within your skill folder to store server-side webhook handlers or other backend logic. You can also use the `scripts/` directory for helper utilities that support the skill's execution, allowing your skill to process external events and data beyond the LLM context. ### Where can I find reference implementations of Codex skills? Reference the template in [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) for the canonical structure and required fields. For a real-world implementation, examine [`plugins/zoom/skills/webhooks/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/SKILL.md), which demonstrates handling external API webhooks and includes comprehensive workflow documentation.