# How to Add Skills to an Existing Codex Plugin: The Complete Developer Guide > Learn how to add skills to an existing Codex plugin. This guide covers creating subdirectories, SKILL.md, and openai.yaml for seamless integration. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-29 --- **To add skills to an existing Codex plugin, create a subdirectory under `skills/` containing 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, 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`](https://github.com/openai/plugins/blob/main/SKILL.md) front-matter, and registers the associated agent from [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml). This registration process makes the skill available for invocation by users or other plugin components through the Codex UI. ```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 ``` ## 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`](https://github.com/openai/plugins/blob/main/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//` in your plugin root. 2. **Add [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)** with valid YAML front-matter containing `name` and `description` fields, followed by workflow documentation. 3. **Create [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md): ```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 ``` Corresponding [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml): ```yaml system: | You are a helpful assistant that generates friendly greetings. temperature: 0.3 max_tokens: 50 tools: [] ``` Resulting folder structure: ```text 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) (with YAML front-matter for `name` and `description`) and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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//` containing at least two files: [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) with valid YAML front-matter (including `name` and `description` fields) and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file to extract metadata and loading the corresponding agent configuration from [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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.