# Understanding the Structure of a Plugin's Skills Directory in OpenAI Plugins > Learn the structure of a plugin's skills directory in the openai/plugins repository. See how SKILL.md and references folders organize plugin capabilities for better understanding. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: article - Published: 2026-06-24 --- **Each plugin in the openai/plugins repository organizes its capabilities within a `skills/` directory containing subfolders for individual skills, each requiring a [`SKILL.md`](https://github.com/openai/plugins/blob/main/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//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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/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`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/SKILL.md) ([view source](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/SKILL.md)) - Supporting documentation: [`plugins/zotero/skills/zotero/references/local-api-routes.md`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/references/local-api-routes.md) ([view source](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/references/local-api-routes.md)) ### 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`](https://github.com/openai/plugins/blob/main/plugins/google-drive/skills/google-slides/SKILL.md) ([view source](https://github.com/openai/plugins/blob/main/plugins/google-drive/skills/google-slides/SKILL.md)) - Reference materials: [`plugins/google-drive/skills/google-slides/references/reference-batch-update-recipes.md`](https://github.com/openai/plugins/blob/main/plugins/google-drive/skills/google-slides/references/reference-batch-update-recipes.md) ([view source](https://github.com/openai/plugins/blob/main/plugins/google-drive/skills/google-slides/references/reference-batch-update-recipes.md)) ### Cloudflare Plugin Structure The Cloudflare plugin's wrangler skill illustrates the minimal required structure: - Core definition: [`plugins/cloudflare/skills/wrangler/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/skills/wrangler/SKILL.md) ([view source](https://github.com/openai/plugins/blob/main/plugins/cloudflare/skills/wrangler/SKILL.md)) - 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: ```markdown 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`](https://github.com/openai/plugins/blob/main/SKILL.md) with proper YAML frontmatter and documentation: ```yaml --- 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//skills/` and contains individual skill subfolders that organize plugin capabilities - Each skill requires a [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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//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`](https://github.com/openai/plugins/blob/main/SKILL.md) file and optional references, allowing plugins to expose diverse capabilities while maintaining the same standardized structure throughout the skills directory.