How to Organize Plugin Assets and Icons in the OpenAI Plugins Repository

Place branding files in a top-level assets/ directory with standardized names like icon.svg, store skill-specific media in skills/<skill-name>/assets/, and reference icons in .codex-plugin/plugin.json using relative paths.

Organizing plugin assets and icons correctly ensures consistent rendering across the Codex interface and Plugin Store. The OpenAI Plugins repository establishes a strict filesystem convention that separates global branding from skill-specific resources. Following this structure guarantees compatibility with automated validation tools and maintains clean version control history for audit trails.

Standard Directory Structure for Plugin Assets

The repository enforces a predictable layout to enable automated discovery by the Codex UI. This convention separates concerns between plugin-wide branding and individual skill resources.

Top-Level Assets Folder

Create an assets/ directory at the repository root to store global branding files. According to the Zoom plugin README, this folder contains "branding and screenshot assets" that appear in the Plugin Store and Codex UI without requiring custom logic.

Include these standardized files:

• icon.svg — Primary scalable logo
• icon.png — PNG fallback format
• icon-small.png — 48×48px for list views
• icon-large.png — 256×256px for detail views
• screenshots/ — UI images for store pages

The Zoom plugin implements this pattern in plugins/zoom/assets/ with icon-small.png and icon-large.png files.

Skill-Specific Asset Directories

Place media belonging to individual skills in skills/<skill-name>/assets/. This prevents accidental bundling of large files into the main plugin package and clarifies which resources belong to specific functionality.

The Shopify plugin demonstrates this convention by storing skill-related resources in plugins/shopify/assets/ as referenced in its skill definition at lines 39-40.

Icon Formats and Naming Conventions

Consistency in filename conventions enables CI/CD pipelines to apply uniform validation rules (e.g., "icon must be ≤ 512 KB"). Always provide multiple formats to ensure cross-browser compatibility.

SVG files (icon.svg) offer scalability for modern devices, while PNG variants (icon-small.png, icon-large.png) provide fallbacks for older browsers and specific display contexts.

The Remotion plugin follows this standard by including icon.svg in plugins/remotion/assets/ according to the asset rules documentation at lines 1-8.

Configuring the Plugin Manifest

The .codex-plugin/plugin.json file declares the plugin and points to visual assets using relative paths from the repository root.

{
  "name": "my-plugin",
  "display_name": "My Plugin",
  "icon": "assets/icon.svg",
  "description": "…"
}

Using relative paths ensures the repository remains portable when moved or forked.

Referencing Assets in Code

When skills need to display branding or skill-specific media, use relative imports to maintain repository mobility.

Import the main logo in a web skill:

import logoUrl from '../../assets/icon.svg';
export const render = () => `<img src="${logoUrl}" alt="My Plugin Logo">`;

Embed screenshots in Markdown documentation:

![My Plugin Logo](../assets/icon.png)

All paths should be relative to the referencing file to prevent breakage during version control operations.

Real-World Implementation Examples

Multiple production plugins in the repository demonstrate these conventions:

Zoom: Stores icon-small.png and icon-large.png in plugins/zoom/assets/ as referenced in its README at lines 14-16.

Shopify: Places skill-related resources in plugins/shopify/assets/ according to its skill definition at lines 39-40.

Remotion: Maintains icon.svg in plugins/remotion/assets/ following the repository asset rules at lines 1-8.

Vercel: Uses plugins/vercel/assets/ for static plugin files as documented in its README at lines 12-13.

Summary

• Place global branding in a top-level assets/ directory with standardized names: icon.svg, icon.png, icon-small.png, and icon-large.png
• Store skill-specific media in skills/<skill-name>/assets/ to avoid bloating the main plugin package
• Define the primary icon path in .codex-plugin/plugin.json using relative references
• Provide both SVG and PNG formats to ensure compatibility across devices and browsers
• Use relative paths in all code and documentation to maintain repository portability

Frequently Asked Questions

Where should I place my plugin's main logo file?

Place the primary logo in the top-level assets/ directory as icon.svg or icon.png. This location is referenced in .codex-plugin/plugin.json and allows the Codex UI to discover your branding automatically, following the pattern established in plugins/zoom/assets/.

What icon sizes and formats are required for OpenAI plugins?

Provide an SVG for scalability plus PNG variants named icon-small.png (48×48px) and icon-large.png (256×256px). The Zoom plugin uses this exact naming convention in plugins/zoom/assets/ to ensure crisp display across different contexts while maintaining fallback compatibility for older browsers.

How do I handle assets that only one skill uses?

Store skill-specific media in skills/<skill-name>/assets/ rather than the global assets/ folder. This separation, demonstrated in the Shopify plugin at plugins/shopify/assets/, prevents unnecessary bundling into the plugin package and clarifies resource ownership.

Should I use absolute or relative paths when referencing assets?

Always use relative paths. In .codex-plugin/plugin.json, reference icons as "assets/icon.svg". In skill code, use relative imports like ../../assets/icon.svg. Relative paths ensure the repository remains functional when moved, forked, or version-controlled without requiring path reconfiguration.

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