How to Include Assets Like Logos and Images in Your OpenAI Plugin

You include assets in an OpenAI plugin by placing image files in the plugins/<plugin-name>/assets/ directory and referencing them via relative paths in the .codex-plugin/plugin.json manifest using the composerIcon, logo, and screenshots fields.

OpenAI plugins follow a self-contained bundle architecture where visual assets are declaratively mapped through the plugin manifest. To include assets like logos and images in your OpenAI plugin, you must place files in a dedicated assets/ directory and configure specific JSON fields that the Codex Marketplace reads at runtime. This guide explains the exact file paths and manifest configurations used in the openai/plugins repository.

Asset Storage and Directory Structure

Every OpenAI plugin stores static assets in a dedicated folder within the plugin root. According to the repository structure, you must create an assets/ directory inside your plugin folder:

plugins/
└─ my-plugin/
   ├─ .codex-plugin/
   │  └─ plugin.json
   └─ assets/
      ├─ logo.svg          # Referenced as composerIcon / logo

      ├─ screenshot-1.png  # Gallery screenshot

      └─ screenshot-2.png  # Additional screenshot

Place all asset files—including SVGs, PNGs, JPGs, and other images—inside this directory. The openai/plugins repository treats this folder as the canonical location for static media that ships with your plugin when published to the Codex Marketplace.

Configuring the Plugin Manifest

The .codex-plugin/plugin.json file controls how the marketplace renders your plugin card and connector UI. You must declare your assets using relative paths that start from the manifest file's location.

Required Manifest Image Fields

Three specific fields control visual asset display:

• composerIcon: The icon displayed in the composer interface. Set this to a relative path like "./assets/logo.svg".
• logo: The main plugin logo shown in marketplace listings and detail cards.
• screenshots: An optional array of paths to screenshot images for gallery displays.

As implemented in plugins/vercel/.codex-plugin/plugin.json, the Vercel plugin demonstrates this exact pattern:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "interface": {
    "displayName": "My Plugin",
    "composerIcon": "./assets/logo-padded.png",
    "logo": "./assets/logo-padded.png",
    "screenshots": [
      "./assets/screenshot-1.png",
      "./assets/screenshot-2.png"
    ]
  }
}

Path Resolution Rules

All paths in the manifest must be relative to the plugin.json file location, not the repository root. The runtime resolves these paths when rendering the plugin in the Codex Marketplace or connector UI. Because these are simple string references, you can swap asset files without touching code; the marketplace UI updates automatically on the next refresh.

Accessing Assets Within Skills

Plugins often need to reference the same images inside skill components or UI elements. The openai/plugins repository supports framework-specific patterns for static file access documented in skill-level guides.

Using staticFile() in Remotion Skills

For video generation skills using Remotion, import the staticFile helper from the Remotion library. Place your image in the skill's public/ directory, then reference it in your component:

import { Img, staticFile } from "remotion"

export const Header = () => {
  return <Img src={staticFile("logo.svg")} style={{ width: 120 }} />
}

The staticFile() function resolves the correct URL at runtime, ensuring the asset loads properly during video composition workflows. This pattern is documented in plugins/remotion/skills/remotion/rules/images.md.

Static Assets in Next.js and Vercel Skills

When building skills with Next.js or deploying to Vercel, copy your assets/ folder contents to the skill's public/ directory during the build process. This makes files accessible at root-relative paths:

export default function Home() {
  return <img src="/assets/logo.svg" alt="My logo" />
}

The build system automatically serves files from public/assets/ at the /assets/ URL path, maintaining consistency between your manifest references and skill component usage.

Key Files and Locations

Understanding the file structure helps maintain consistency across your plugin development:

• .codex-plugin/plugin.json: The manifest file where you declare composerIcon, logo, and screenshots with relative paths to bundled assets.
• plugins/<plugin-name>/assets/: The directory containing actual image files shipped with the plugin to the Codex Marketplace.
• Skill public/ folders: Locations for framework-specific static assets accessed via helpers like staticFile() or direct URL references.

Summary

• Place all logos, icons, and screenshots in plugins/<plugin-name>/assets/ to ensure they ship with your plugin bundle.
• Reference assets in .codex-plugin/plugin.json using relative paths in the composerIcon, logo, and screenshots fields.
• Use staticFile("filename") for Remotion skills and public/ directories for Next.js/Vercel skills to access images within components.
• Asset updates require no code changes—simply replace files in the assets/ directory and refresh the marketplace display.

Frequently Asked Questions

What image formats are supported for OpenAI plugin assets?

The openai/plugins repository accepts standard web image formats including SVG, PNG, and JPG. SVG files are recommended for logos and icons due to their scalability, while PNG works best for screenshots requiring transparency or photographic detail.

Can I use external URLs instead of local asset files?

The manifest fields composerIcon, logo, and screenshots expect relative paths pointing to files inside your plugin's assets/ directory. While external URLs might work in some skill implementations, the marketplace rendering system specifically looks for bundled assets to ensure availability and version control consistency.

How do I reference the same logo in both the manifest and a skill component?

Store the master file in plugins/<plugin-name>/assets/, reference it in .codex-plugin/plugin.json using a relative path like "./assets/logo.svg", then copy or symlink the file to your skill's public/ folder. For Remotion skills, use staticFile("logo.svg"); for Next.js, reference it as /assets/logo.svg after ensuring the build process copies the file to the public directory.

Why aren't my assets showing in the Codex Marketplace?

Verify that your paths in .codex-plugin/plugin.json are relative to the manifest file location (starting with ./assets/), confirm the files exist in the plugins/<plugin-name>/assets/ directory, and ensure the files are committed to version control. The marketplace only displays assets that are physically present in the plugin bundle.

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