# Organizing Reference Files and Assets Within Plugin Directories: A Complete Guide to the OpenAI Plugins Structure

> Learn the OpenAI plugins structure and organize reference files assets efficiently. Discover best practices for plugin directories, assets, documentation and metadata.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Place visual assets in the plugin-level `assets/` folder, detailed documentation in `skills/<skill>/references/`, and discovery metadata in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to maintain a discoverable, modular structure.**

The `openai/plugins` repository enforces a strict directory hierarchy that separates code, documentation, and visual resources into predictable locations. This organizational pattern ensures that when you are organizing reference files and assets within plugin directories, every resource—from authentication guides to application icons—remains discoverable by both the Codex platform and human contributors.

## Repository Structure at a Glance

Every plugin follows a consistent scaffold. At the root of the repository, the `plugins/` directory contains individual plugin folders, each structured as follows:

```text
plugins/
└─ <plugin-name>/
   ├─ .codex-plugin/          # Plugin manifest and metadata

   ├─ .app.json               # Optional runtime configuration

   ├─ assets/                 # Icons, logos, and visual resources

   └─ skills/
      └─ <skill-name>/
         ├─ SKILL.md          # Entry point: workflow, guardrails, verification

         ├─ agents/           # UI metadata (e.g., openai.yaml)

         ├─ references/       # Markdown reference documentation

         ├─ scripts/          # Helper smoke-test scripts

         └─ examples/         # Sample prompts and usage snippets

```

This layout keeps the three concerns—configuration, presentation, and logic—isolated while maintaining clear linkages between them.

## Plugin-Level Configuration

### The Plugin Manifest (.codex-plugin/plugin.json)

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file serves as the source of truth for the plugin's identity and capabilities. It declares the plugin name, version, and the relative path to its skills directory. In [`plugins/box/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/box/.codex-plugin/plugin.json), the manifest points to the local `./skills/` folder:

```json
{
  "name": "box",
  "skills": "./skills/",
  "interface": {
    "logo": "./assets/app-icon.png",
    "composerIcon": "./assets/app-icon.png"
  }
}

```

The `interface` block specifically references assets stored in the `assets/` directory, linking the visual identity to the plugin's functional entry points.

### Runtime Configuration (.app.json)

The optional [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file contains runtime settings used by the Codex platform. For simple plugins, this file may remain empty, but it must be present to signal compatibility with the runtime environment.

## Managing Visual Assets

All visual assets reside in the plugin-level `assets/` folder. These files are never mixed with code or documentation. The Box plugin, for example, stores `app-icon.png` and `box.svg` in `plugins/box/assets/`, referenced directly by the manifest's `interface` properties `composerIcon` and `logo`.

When adding new assets, place them in this dedicated folder and update the corresponding paths in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). This separation prevents merge conflicts between design updates and functional code changes.

## Skill Architecture and Reference Files

Each functional area within a plugin is called a **skill**. The `skills/` directory contains subdirectories for each capability, with standardized internal structures that govern how reference files and assets are organized.

### SKILL.md: The Central Entry Point

Every skill must contain a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file at its root. This document acts as the master workflow guide, defining guardrails, verification steps, and links to detailed reference materials. Located at `plugins/<plugin>/skills/<skill>/SKILL.md`, this file is the first resource the Codex platform reads when loading a skill.

### The References Directory

Detailed documentation lives in `references/`. These Markdown files contain specific guidance on authentication, API usage, bulk operations, and other technical details. For instance, the Box plugin stores authentication instructions in [`plugins/box/skills/box/references/auth-and-setup.md`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/references/auth-and-setup.md).

The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) links to these files using relative paths, creating a navigable documentation tree:

```markdown
Read only the matching reference files:
- Auth setup … `references/auth-and-setup.md`
- Box CLI … `references/box-cli.md`

```

### Supporting Components (agents, scripts, examples)

- **agents/**: Contains [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) and other UI metadata that makes the skill discoverable in the Codex interface.
- **scripts/**: Houses small Python or Node.js utilities for local smoke testing, such as [`plugins/box/skills/box/scripts/box_cli_smoke.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_cli_smoke.py).
- **examples/**: Stores sample prompts and usage snippets, like [`plugins/box/skills/box/examples/box-content-api-prompts.md`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/examples/box-content-api-prompts.md).

## Naming Conventions

Consistency in naming ensures programmatic discoverability:

- **Plugin folders**: Lowercase, hyphen-separated (e.g., `box`, `zoom`).
- **Skill folders**: Match the plugin name for single-skill plugins, or use descriptive names (e.g., `zoom-apps-sdk`) for multi-skill integrations.
- **Reference files**: Snake-case with descriptive suffixes (e.g., [`auth-and-setup.md`](https://github.com/openai/plugins/blob/main/auth-and-setup.md), [`bulk-operations.md`](https://github.com/openai/plugins/blob/main/bulk-operations.md)).
- **Asset files**: Descriptive names like `app-icon.png` or `logo.svg`.
- **Scripts**: Snake-case indicating purpose (e.g., [`box_cli_smoke.py`](https://github.com/openai/plugins/blob/main/box_cli_smoke.py)).

## Cross-Linking Reference Documentation

Because [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) serves as the entry point, it functions as an index to the skill's reference materials. Using relative paths in Markdown bullet lists ensures links resolve correctly both in GitHub's viewer and within the Codex runtime environment. This cross-linking strategy prevents documentation fragmentation and eliminates hidden or orphaned reference files.

## Programmatically Locating Resources

When building tooling around the repository, you can locate reference files and assets deterministically using the established paths.

To resolve a reference file path in Python:

```python
import pathlib

def get_reference_path(plugin: str, skill: str, filename: str) -> pathlib.Path:
    """
    Return the absolute path to a reference markdown file inside a plugin.
    """
    base = pathlib.Path(__file__).parent.parent / "plugins" / plugin / "skills" / skill / "references"
    return base / filename

# Example: path to Box auth docs

auth_path = get_reference_path("box", "box", "auth-and-setup.md")
print(auth_path)   # → .../plugins/box/skills/box/references/auth-and-setup.md

```

To list all assets for a plugin in Bash:

```bash

# Bash one-liner to list all assets for a plugin

PLUGIN=box
find plugins/$PLUGIN/assets -type f -printf "%f\n"

# Output:

# app-icon.png

# box.svg

# box-small.svg

```

## Adding New Reference Files and Assets

### Creating a New Reference Document

1. Create the Markdown file under `plugins/<plugin>/skills/<skill>/references/` using snake-case naming (e.g., [`rate-limiting.md`](https://github.com/openai/plugins/blob/main/rate-limiting.md)).
2. Update [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) to include a bullet linking to the new file:

   ```markdown
   - Rate limiting guidelines … `references/rate-limiting.md`
   ```

3. Optionally, add a verification script in `scripts/` that exercises the documented feature.

### Adding Visual Assets

1. Place the image file (PNG or SVG) in `plugins/<plugin>/assets/`.
2. Reference the asset in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) under the `interface` object:

   ```json
   "interface": {
       "logo": "./assets/new-logo.png",
       "composerIcon": "./assets/new-logo.png"
   }
   ```

## Summary

- **Plugin manifests** in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) declare skills and asset locations, establishing the root of the organization tree.
- **Visual assets** belong exclusively in the plugin-level `assets/` folder, never mixed with code or documentation.
- **Reference documentation** resides in `skills/<skill>/references/` and is indexed by [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) using relative Markdown links.
- **Naming conventions** enforce lowercase, hyphen-separated directories and snake-case files, ensuring predictable path resolution.
- **Programmatic access** follows the `plugins/<name>/skills/<skill>/` pattern, allowing scripts to locate resources without hardcoding full paths.

## Frequently Asked Questions

### What is the purpose of the references/ directory in an OpenAI plugin?

The `references/` directory stores detailed Markdown documentation that [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) links to for specific workflows. Files like [`auth-and-setup.md`](https://github.com/openai/plugins/blob/main/auth-and-setup.md) contain deep technical guidance that would clutter the main entry point, keeping [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) focused on high-level workflow and guardrails while delegating implementation details to the references folder.

### How do I add a new icon or logo to my plugin?

Place the image file in `plugins/<plugin-name>/assets/`, then update the `interface` block in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to point to the new file using a relative path like `./assets/logo.png`. The `logo` and `composerIcon` properties control how the plugin appears in the Codex UI.

### What should be included in SKILL.md?

[`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) should contain the primary workflow description, operational guardrails, verification steps, and a curated list of links to files in the `references/` directory. It acts as the table of contents for the skill, guiding both the AI and developers through the available capabilities without duplicating the detailed content stored in reference files.

### How does the plugin manifest discover available skills?

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file includes a `skills` property that specifies the relative path to the skills directory (typically `"./skills/"`). The platform scans this directory for subdirectories containing [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files, automatically registering each as an available capability without requiring manual enumeration in the manifest.