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 specification and an 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, you must provide specific files for Codex to recognize and load your skill.

SKILL.md - The Skill Specification

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

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

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/<skill-name>/ in your plugin root.
2. Add 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 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 front-matter, and registers the associated agent configurations.

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 file demonstrates the required layout and fields for any new skill. For a concrete example, examine 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/<skill-name>/ directory within your plugin root.
• Each skill requires a SKILL.md file with YAML front-matter defining name and description.
• The 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 with YAML front-matter containing name and description fields, and an 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 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 for the canonical structure and required fields. For a real-world implementation, examine plugins/zoom/skills/webhooks/SKILL.md, which demonstrates handling external API webhooks and includes comprehensive workflow documentation.

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