What Does the Skills Directory Contain in an OpenAI Plugin?

The skills directory contains self-contained capability definitions—each with a manifest, optional agent configurations, execution scripts, static assets, and reference documentation—that expose specific functions to the model.

The skills directory serves as the central nervous system of every plugin in the openai/plugins repository. It houses the atomic capabilities that the model can discover, reason about, and execute during a conversation. Understanding the contents and structure of this directory is essential for developers building or debugging OpenAI plugins.

The Core Components of the Skills Directory

Each subdirectory within skills/ represents a discrete capability. According to the openai/plugins source code, every skill follows a standardized layout that includes five primary components.

SKILL.md: The Capability Manifest

The SKILL.md file serves as the primary contract between the model and the capability. This markdown manifest declares the skill's name, description, step-by-step workflow, and usage constraints.

For example, the Canva translation skill at plugins/canva/skills/canva-translate-design/SKILL.md defines a six-step workflow: locating the design, creating a translated copy, initiating an editing transaction, translating text elements, applying replacements in batch, and committing the transaction after user approval.

agents/: Model Mapping and Binary Requirements

The optional agents/ subdirectory contains YAML files—typically openai.yaml—that map the skill to specific model configurations. These files declare the command name, required binaries, and environment constraints necessary for execution.

When a skill depends on external CLI tools, the agent definition enforces availability. For instance, a skill using the Unified Commerce Protocol CLI includes this declaration in agents/openai.yaml:

name: ucp
command: ucp
requires_bin: ucp
description: |
  Interact with the Unified Commerce Protocol (UCP) CLI to search,
  cart, checkout, and order products.

If the ucp binary is absent, the runtime can trigger a graceful fallback or user notification.

scripts/: Execution Logic and API Integration

The scripts/ folder contains the implementation code—Python, JavaScript, or shell scripts—that performs the skill's heavy lifting. These scripts handle API calls, data transformation, and file operations.

The Zotero plugin demonstrates this pattern with plugins/zotero/skills/zotero/scripts/zotero.py, which manages bibliography operations locally.

assets/: Visual Resources and UI Artifacts

Static media lives in the assets/ directory. This includes icons, screenshots, and other visual artifacts that the skill may return to users during interaction.

The Canva plugin stores its logo at plugins/canva/assets/logo.png, making visual identification available throughout the workflow.

references/: Contextual Documentation and Schemas

Supplementary documentation resides in references/, including JMESPath view definitions, API route documentation, and implementation notes that provide additional context to the model.

The Zotero skill includes plugins/zotero/skills/zotero/references/local-api-routes.md to document endpoint specifications beyond the core manifest.

Recursive Organization and Capability Isolation

The skills directory supports recursive nesting. A plugin may contain multiple top-level skills, each maintaining its own isolated subdirectories for scripts, assets, and references.

This structure ensures atomic capabilities—each skill is self-contained, versioned independently, and discoverable by the model without cross-dependencies. When the model detects intent like "translate my design to French," it selects the specific skill subdirectory and loads only the relevant manifest and scripts.

Runtime Invocation Flow

When a user triggers a capability, the model constructs a JSON payload targeting the specific skill. For the Canva translation example:

{
  "name": "canva-translate-design",
  "inputs": {
    "design_id": "DABcd1234ef",
    "target_language": "fr"
  }
}

The runtime then executes the workflow defined in that skill's SKILL.md, utilizing scripts from the scripts/ folder and validating binary requirements against the agents/openai.yaml specifications.

Summary

• The skills directory contains self-contained capability units in the openai/plugins repository, each exposing specific functions to the model.
• Every skill requires a SKILL.md manifest that defines workflows and constraints, stored at paths like plugins/{name}/skills/{skill-name}/SKILL.md.
• Optional agents/openai.yaml files declare command mappings and binary requirements (requires_bin) for external dependencies.
• Implementation logic resides in the scripts/ subdirectory, while visual assets populate assets/ and supplemental documentation lives in references/.
• The recursive structure allows plugins to host multiple isolated capabilities, ensuring atomic discovery and execution by the model.

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 capability manifest, providing the model with a human-readable description of the skill's purpose, step-by-step workflow, and usage constraints. It enables the model to understand how to invoke the skill and what inputs to expect, serving as the primary documentation source located at skills/{skill-name}/SKILL.md.

How does the agents directory enforce binary requirements?

The agents/ subdirectory contains YAML configurations—typically openai.yaml—that declare requires_bin fields specifying external CLI tools needed for execution. When the model attempts to run a skill, the runtime checks for these binaries; if absent, the system can gracefully fall back to alternative skills or notify the user rather than failing silently.

Can a single plugin contain multiple skills?

Yes. The skills directory supports recursive organization, allowing a plugin to define multiple top-level capability folders. Each skill maintains isolated subdirectories for scripts/, assets/, and references/, ensuring that the model treats each capability as an atomic unit during discovery and invocation.

What types of files belong in the scripts subdirectory?

The scripts/ folder contains executable code that performs the skill's core operations, including API clients, data transformation utilities, and file handling logic. These scripts may be written in Python, JavaScript, shell, or other languages, such as plugins/zotero/skills/zotero/scripts/zotero.py which manages local bibliography operations.

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