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

Place visual assets in the plugin-level assets/ folder, detailed documentation in skills/<skill>/references/, and discovery metadata in .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:

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 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, the manifest points to the local ./skills/ folder:

{
  "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 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. 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 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.

The SKILL.md links to these files using relative paths, creating a navigable documentation tree:

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 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.
• examples/: Stores sample prompts and usage snippets, like 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, 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).

Cross-Linking Reference Documentation

Because 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:

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 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).

2. Update SKILL.md to include a bullet linking to the new file:

   - 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 under the interface object:

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

Summary

• Plugin manifests in .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 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 links to for specific workflows. Files like auth-and-setup.md contain deep technical guidance that would clutter the main entry point, keeping 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 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 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 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 files, automatically registering each as an available capability without requiring manual enumeration in the manifest.

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