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

> Organize OpenAI plugin assets and icons effectively with best practices. Learn to structure your files in the openai plugins repository to ensure clarity and compliance.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-07-04

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file declares the plugin and points to visual assets using relative paths from the repository root.

```json
{
  "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:

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

```

Embed screenshots in Markdown documentation:

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