# What Does the Skills Directory Contain in an OpenAI Plugin?

> Explore the skills directory in OpenAI plugins. Discover how capability definitions, manifests, agent configurations, and execution scripts expose functions to the model for enhanced functionality.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: internals
- Published: 2026-09-12

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml):

```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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

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

```

The runtime then executes the workflow defined in that skill's [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md), utilizing scripts from the `scripts/` folder and validating binary requirements against the [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md)** manifest that defines workflows and constraints, stored at paths like `plugins/{name}/skills/{skill-name}/SKILL.md`.
- Optional **[`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/scripts/zotero.py) which manages local bibliography operations.