How Skills Are Defined in the OpenAI Plugins Repository: A Technical Guide

A skill is the smallest reusable building block in the OpenAI plugins system, defined by a standalone folder containing a SKILL.md file with YAML front-matter that specifies the skill's machine-readable identifier and workflow.

The openai/plugins repository implements a modular architecture where each plugin exposes capabilities through discrete, discoverable units called skills. Understanding how these skills are defined is essential for developers building Codex-compatible plugins or extending existing integrations. This guide examines the canonical structure, discovery mechanisms, and implementation patterns used throughout the repository.

The Skill Directory Structure

Each skill resides in a self-contained folder within the plugin's declared skills directory. According to the source code analysis, a valid skill definition requires specific components that work together to provide both human-readable documentation and machine-interpretable metadata.

The Manifest Declaration

Every plugin declares its skills directory in the .codex-plugin/plugin.json manifest file. The skills field points to the relative path containing all skill subdirectories.

{
  "name": "zoom",
  "skills": "./skills/",
  ...
}

Source: .codex-plugin/plugin.json

The Codex loader uses this path as the root for scanning subdirectories. Any folder containing a SKILL.md file is registered as a valid skill.

The SKILL.md File

The SKILL.md file serves as the canonical definition of the skill. It must begin with YAML front-matter containing the skill's machine-readable identifier and description, followed by markdown content explaining the workflow.

---
name: setup-zoom-webhooks
description: Use when building Zoom webhooks.
---

# Setup Zoom Webhooks

Use this skill when the integration receives Zoom events over HTTP. …

Source: plugins/zoom/skills/webhooks/SKILL.md

The front-matter name field becomes the skill's unique identifier referenced by the agent during request routing. The body describes when to use the skill, the step-by-step workflow, and links to reference materials.

Supporting Assets

Skills may include optional implementation directories that separate documentation from executable code:

• scripts/ – Contains JavaScript, TypeScript, or Python files implementing the skill's functionality (e.g., REST API calls or data processing)
• references/ – Houses supplementary documentation such as API specifications, event schemas, or troubleshooting guides
• Additional markdown files – Provide usage examples, design notes, or advanced configuration options

For example, the Zoom webhook skill references supplementary guides in its markdown:

- Full preserved guide: [references/full-guide.md](references/full-guide.md)
- Signature verification: [references/signature-verification.md](references/signature-verification.md)

Sources: plugins/zoom/skills/webhooks/references/full-guide.md, plugins/zoom/skills/webhooks/references/signature-verification.md

Runtime Discovery and Loading

The plugin initialization process automatically discovers and registers skills using the plugin-eval library. In plugins/plugin-eval/src/evaluators/plugin.js, the discoverPluginSkillDirectories function traverses the skills directory identified in the manifest.

// plugins/plugin-eval/src/evaluators/plugin.js
const skillDirs = await discoverPluginSkillDirectories(pluginRoot, manifest);

This routine returns each subfolder containing a SKILL.md file. The loader parses the YAML front-matter to extract the skill name and description, then adds the skill to the plugin's runtime catalogue for the Codex agent to invoke.

Practical Implementation Examples

Invoking a Skill from Agent Context

When processing user requests, the Codex agent matches queries to skill identifiers defined in the front-matter name field:

User: I need a Zoom webhook that notifies me when a meeting ends.
Assistant: [setup-zoom-webhooks]

The agent references the setup-zoom-webhooks skill ID and follows the workflow described in the corresponding SKILL.md.

Accessing Skill References Programmatically

Reference documentation can be loaded directly for runtime guidance:

import fs from "fs";

const guide = fs.readFileSync(
  "plugins/zoom/skills/webhooks/references/signature-verification.md",
  "utf-8"
);
console.log(guide);

Utilizing Skill Scripts

Skills that ship with implementation code expose reusable utilities:

from plugins.zoom.skills.webhooks.scripts.verify_signature import verify_signature

def handle_event(request):
    payload = request.json()
    if verify_signature(payload, request.headers["Zoom-Signature"]):
        # Process event

        pass

Summary

• Skills are defined as standalone folders within a plugin's declared skills directory, each containing a mandatory SKILL.md file.
• The .codex-plugin/plugin.json manifest specifies the skills path that the discovery mechanism scans during initialization.
• SKILL.md files require YAML front-matter with name and description fields to register as machine-readable capabilities.
• The discoverPluginSkillDirectories function in plugins/plugin-eval/src/evaluators/plugin.js handles runtime discovery and catalogue population.
• Optional scripts/ and references/ directories contain implementation code and supplementary documentation, respectively.

Frequently Asked Questions

What is the minimum required file structure to define a skill?

A valid skill requires only a SKILL.md file inside a subfolder of the plugin's skills directory. The file must contain YAML front-matter with a name field and a description field. While scripts/ and references/ directories are optional, they are commonly included to separate implementation logic from documentation.

How does the Codex agent know which skill to invoke for a specific request?

The runtime discovery process parses the name field from each SKILL.md front-matter block during plugin initialization. When processing user requests, the agent matches the intent to these registered skill identifiers. The workflow description in the markdown body guides the agent's subsequent actions.

Can a skill include executable code, or is it documentation-only?

A skill can include executable code by placing scripts in a scripts/ directory within the skill folder. These files can be written in JavaScript, TypeScript, or Python and are imported or referenced by the agent when executing the skill's workflow. However, the SKILL.md remains the canonical definition required for discovery.

Where does the discovery logic reside in the repository?

The skill discovery logic is implemented in plugins/plugin-eval/src/evaluators/plugin.js. Specifically, the discoverPluginSkillDirectories function takes the plugin root and manifest as arguments, walks the directory tree specified by the skills field, and returns all paths containing SKILL.md files for catalogue registration.

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