Understanding the Structure of a Plugin's Skills Directory in OpenAI Plugins

Each plugin in the openai/plugins repository organizes its capabilities within a skills/ directory containing subfolders for individual skills, each requiring a SKILL.md file and optionally supporting documentation in a references/ folder.

In the openai/plugins repository, every plugin follows a standardized layout that enables the Codex engine to discover and load capabilities automatically. The skills directory serves as the central location where each plugin defines its discrete capabilities through structured metadata and documentation. Understanding this layout is essential for developers contributing new skills or maintaining existing integrations.

Directory Hierarchy and File Organization

The skills directory follows a consistent hierarchical pattern across all plugins. Located at plugins/<plugin-name>/skills/, this directory contains one subfolder per skill, creating a predictable structure that the Codex engine traverses when loading plugin capabilities.

The SKILL.md File

Every skill folder must contain a SKILL.md file that serves as the primary entry point. This file uses YAML frontmatter to define required metadata fields including name and description, followed by markdown documentation that explains the skill's functionality and usage patterns. The Codex engine parses this file to understand what capabilities the skill exposes.

The References Directory

Optional supporting materials reside in a sibling references/ directory within the skill folder. This directory typically contains supplementary documentation such as API specifications, troubleshooting guides, example prompts, or architectural diagrams that the main SKILL.md file links to for additional context.

Real-World Examples from the Repository

The uniform structure appears consistently across all plugins in the openai/plugins repository.

Zotero Plugin Structure

The Zotero plugin demonstrates the complete layout with its zotero skill:

• Core definition file: plugins/zotero/skills/zotero/SKILL.md (view source)
• Supporting documentation: plugins/zotero/skills/zotero/references/local-api-routes.md (view source)

Google Drive Plugin Structure

For Google Slides functionality within the Google Drive plugin, the structure includes:

• Core definition: plugins/google-drive/skills/google-slides/SKILL.md (view source)
• Reference materials: plugins/google-drive/skills/google-slides/references/reference-batch-update-recipes.md (view source)

Cloudflare Plugin Structure

The Cloudflare plugin's wrangler skill illustrates the minimal required structure:

• Core definition: plugins/cloudflare/skills/wrangler/SKILL.md (view source)
• No dedicated references folder, demonstrating that supplementary documentation is optional

Creating a New Skill

To implement a new skill within an existing plugin, create the standardized directory structure and required definition files.

First, establish the directory layout:

plugins/example-plugin/
│
└─ skills/
   ├─ new-skill/
   │   ├─ SKILL.md          # Core skill definition

   │   └─ references/
   │       └─ api-details.md   # Optional supporting documentation

   └─ existing-skill/
       └─ SKILL.md

Then, populate the SKILL.md with proper YAML frontmatter and documentation:

---
name: new-skill
description: A brief description of what the skill does.
---

# New Skill

Documentation goes here detailing how to use the skill...

Summary

• The skills directory lives at plugins/<plugin-name>/skills/ and contains individual skill subfolders that organize plugin capabilities
• Each skill requires a SKILL.md file with YAML frontmatter defining the name and description fields that the Codex engine uses for discovery
• Optional references folders within skill directories contain supplementary documentation such as API specifications, troubleshooting guides, and example prompts
• This structure is consistent across all plugins in the openai/plugins repository, including Zotero, Google Drive, and Cloudflare implementations

Frequently Asked Questions

What is the purpose of the SKILL.md file in a plugin's skills directory?

The SKILL.md file acts as the mandatory entry point that the Codex engine parses when loading a skill. It contains YAML frontmatter with metadata fields including name and description, followed by markdown documentation that explains the skill's functionality, parameters, and usage patterns.

Is the references folder mandatory for every skill in the directory?

No, the references/ directory is optional. While many skills include supporting documentation such as API specifications or troubleshooting guides in this folder, others function with only the core SKILL.md file, as demonstrated by the Cloudflare plugin's wrangler skill.

Where is the skills directory located within a plugin's structure?

The skills directory is located at plugins/<plugin-name>/skills/ relative to the repository root. Each subfolder within this directory represents a distinct skill available to that specific plugin, following the standardized structure used across the openai/plugins repository.

Can a single plugin contain multiple skills in its directory?

Yes, a single plugin can contain multiple skill subfolders within its skills/ directory. Each skill operates independently with its own SKILL.md file and optional references, allowing plugins to expose diverse capabilities while maintaining the same standardized structure throughout the skills directory.

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