# How to Create Skills with Subdirectories in the OpenAI Plugins Repository > Learn to create skills with subdirectories in the OpenAI plugins repository by organizing self contained folders under skills with mandatory SKILL.md files and optional assets. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-28 --- **Creating a skill with subdirectories in the OpenAI Plugins repository requires placing a self-contained folder under `skills/` containing a mandatory [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file and optional guard-rail configurations or supporting assets.** The OpenAI Plugins repository organizes capabilities through modular skills that live in isolated subdirectories. Each skill is a self-contained unit placed under a plugin's `skills/` directory, enabling automatic discovery and clean separation of concerns. Understanding how to create skills with subdirectories allows developers to extend plugins with new capabilities while maintaining the repository's architectural standards. ## Understanding the Skill Subdirectory Structure In the OpenAI Plugins codebase, a **skill** is always a self-contained folder placed under a plugin's `skills/` directory. This subdirectory houses the skill's manifest, optional guard-rail configurations, and any supporting assets required for execution. The canonical layout follows this pattern: ``` plugins// ├── .codex-plugin/ ├── assets/ ├── commands/ ├── agents/ ├── skills/ ← all skill subfolders live here │ └── / ← one folder per skill │ ├── SKILL.md ← skill manifest (required) │ ├── agents/ │ │ └── openai.yaml ← optional guard-rail config │ └── references/ ← optional supplemental docs └── ... ``` This structure provides **isolation** by keeping each skill's metadata, code, and assets together, preventing name clashes across the plugin. The plugin loader automatically scans `skills/*/SKILL.md` to register skills without manual configuration. ## Required Files for Every Skill Every skill subdirectory must contain a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file at its root. This file serves as the skill's manifest and follows the Agent Skills specification. ### The SKILL.md Manifest The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file requires YAML front-matter containing at minimum the `name` and `description` fields: ```markdown --- name: my-awesome-skill description: >- Generates a short description of a project and suggests next steps. --- # My Awesome Skill ## Overview This skill analyses a short project description and returns a concise summary plus three actionable next-step suggestions. ## Usage Invoke it explicitly with `$my-awesome-skill` in a Codex session. ``` According to the source code analysis, the plugin discovery mechanism specifically looks for `skills/*/SKILL.md` patterns to identify available capabilities. Without this file, the skill will not be recognized by the plugin loader. ## Optional Configurations and Assets Beyond the required manifest, skill subdirectories support several optional components that enhance functionality and security. ### Guard-Rail Configuration You may include an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file to control invocation policies. This is particularly important for skills that should only run when explicitly called: ```yaml # plugins/example-plugin/skills/my-awesome-skill/agents/openai.yaml policy: allow_implicit_invocation: false ``` Setting `allow_implicit_invocation: false` prevents the skill from being triggered automatically by the agent, requiring explicit user invocation instead. ### Supporting Directories - **`references/`** – Stores supplemental documentation the skill may access during execution - **`scripts/`** – Contains helper scripts or CLI utilities specific to the skill - **`assets/`** – Houses images, data files, or other static resources These directories are conventional rather than enforced, allowing flexibility in skill implementation while maintaining predictable organization. ## Step-by-Step: Creating a New Skill Follow these steps to create a skill with subdirectories in your plugin: 1. **Navigate to the plugin's skills directory** – Locate or create `plugins//skills/`. 2. **Create a unique folder name** – Use kebab-case or descriptive naming for your skill subdirectory (e.g., `my-awesome-skill`). 3. **Add the SKILL.md manifest** – Create [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) with proper YAML front-matter including `name` and `description` fields. 4. **(Optional) Configure guard-rails** – Add [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) to set `policy.allow_implicit_invocation` based on your security requirements. 5. **(Optional) Add supporting files** – Include reference documentation, scripts, or assets in appropriately named subdirectories. The plugin system will automatically detect your new skill on the next load cycle by scanning for the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file within your new subdirectory. ## Real-World Examples from the Repository The OpenAI Plugins repository demonstrates this pattern across multiple production plugins. ### Twilio Developer Kit Structure The [`plugins/twilio-developer-kit/skills/README.md`](https://github.com/openai/plugins/blob/main/plugins/twilio-developer-kit/skills/README.md) documents the canonical layout for skill subdirectories, emphasizing that skills live directly under `skills/` without additional product-category folders. This ensures the loader correctly identifies `skills/*/SKILL.md` patterns. ### Zoom Plugin Implementation The Zoom plugin provides a complete example in [`plugins/zoom/skills/start/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/start/SKILL.md). This skill includes: - Comprehensive YAML front-matter with detailed descriptions - Explicit invocation policy configured in [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) - Structured documentation following the Agent Skills spec As documented in [`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md), the Zoom plugin discovers skills by scanning `skills/*/SKILL.md` and supports explicit-only invocation patterns for sensitive operations. ## Summary - **Skills require subdirectories** – Each skill must be a self-contained folder under `plugins//skills/`. - **SKILL.md is mandatory** – The plugin loader scans `skills/*/SKILL.md` to discover and register skills automatically. - **Guard-rails are optional but recommended** – Use [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) to control implicit invocation via `policy.allow_implicit_invocation`. - **Supporting assets belong in the subdirectory** – Keep references, scripts, and assets co-located with the skill for maintainability. - **Naming matters** – Use descriptive folder names that reflect the skill's purpose and match the name declared in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) front-matter. ## Frequently Asked Questions ### What happens if I don't include a SKILL.md file in the subdirectory? The plugin loader will not recognize the directory as a valid skill. According to the discovery mechanism implemented in the OpenAI Plugins repository, the system specifically scans for `skills/*/SKILL.md` patterns to identify available capabilities. Without this manifest file, the skill will not appear in the plugin's registry or be available for invocation. ### Can I nest skills within subdirectories of subdirectories? No, the plugin loader expects a flat structure where skills are immediate children of the `skills/` directory. The discovery pattern `skills/*/SKILL.md` looks only one level deep. Nesting skills within additional subdirectories will prevent the loader from finding the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) manifest, effectively hiding those skills from the system. ### How do I prevent a skill from being invoked automatically? Create an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) file inside your skill's subdirectory and set `policy.allow_implicit_invocation: false`. This configuration, as seen in the Zoom plugin's implementation, forces users to invoke the skill explicitly using the `$skill-name` syntax rather than allowing the AI agent to trigger it automatically during conversation. ### Are there naming conventions for skill subdirectories? While the repository enforces no strict naming policy, use descriptive, kebab-case folder names that match the `name` field in your [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) front-matter. The folder name becomes part of the skill's identity within the file system, and consistency between the folder name and manifest name improves maintainability and debugging clarity.