How to Create Skills with Subdirectories in the OpenAI Plugins Repository

Creating a skill with subdirectories in the OpenAI Plugins repository requires placing a self-contained folder under skills/ containing a mandatory 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/<plugin-name>/
├── .codex-plugin/
├── assets/
├── commands/
├── agents/
├── skills/                    ← all skill subfolders live here
│   └── <skill-name>/          ← 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 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 file requires YAML front-matter containing at minimum the name and description fields:

---
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 file to control invocation policies. This is particularly important for skills that should only run when explicitly called:

# 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/<your-plugin>/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 with proper YAML front-matter including name and description fields.

4. (Optional) Configure guard-rails – Add 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 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 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. This skill includes:

• Comprehensive YAML front-matter with detailed descriptions
• Explicit invocation policy configured in agents/openai.yaml
• Structured documentation following the Agent Skills spec

As documented in 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/<plugin-name>/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 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 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 manifest, effectively hiding those skills from the system.

How do I prevent a skill from being invoked automatically?

Create an 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 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.

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