# How to Structure Plugin Assets and Resource Files in OpenAI Plugins

> Learn how to structure plugin assets and resource files effectively for OpenAI Plugins. Organize your manifest, runtime config, static media, and capabilities with this clear guide.

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

---

**Structure plugin assets and resource files by placing the manifest in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), runtime config in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), static media in `assets/`, and optional capabilities in `skills/` and `agents/` directories under `plugins/<plugin-name>/`.**

The `openai/plugins` repository defines a standardized layout for building ChatGPT-compatible plugins. Following this convention ensures your integration loads correctly and displays properly in the OpenAI ecosystem.

## Core Directory Layout

Every plugin in the repository lives under the top-level `plugins/` directory. Each integration occupies its own subdirectory named after the service (e.g., `docusign`, `github`, `zoom`).

Inside each plugin folder, you must include specific files that declare metadata and configuration:

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – Declares the plugin’s metadata, API endpoints, authentication scheme, and OpenAPI specification URL in the format expected by the Codex marketplace.
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** – Stores runtime settings that the OpenAI host reads when loading the plugin, including environment variables and feature flags.
- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** – Provides human-readable documentation, installation steps, and usage instructions.

## Managing Static Assets

Static resources such as icons, logos, and other UI media belong in the dedicated `assets/` directory.

### The assets/ Directory

The `assets/` folder holds any image format (PNG, SVG, etc.) that the plugin UI displays. Keeping all static media together ensures packaging tools can bundle them cleanly for distribution.

### Referencing Assets in the Manifest

Icons are referenced in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) using relative paths from the plugin root. For example, the Docusign plugin declares its icon as follows:

```json
{
  "name": "Docusign",
  "description": "Create and manage envelopes",
  "icon": "assets/icon.png"
}

```

When the OpenAI runtime renders the plugin card, it resolves `assets/icon.png` relative to the `plugins/docusign/` folder.

## Optional Capability Extensions

Beyond the required files, plugins can include optional directories that expose specialized behaviors.

### Skill Definitions (skills/)

The `skills/` directory contains skill definitions and reference documentation that expose higher-level actions (e.g., a "create-envelope" skill for Docusign). Each skill typically includes a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file documenting the capability and may contain a `references/` folder for additional links or snippets.

### Agent Configuration (agents/)

When a plugin uses an OpenAI agent for orchestrating calls, YAML files in `agents/` define system prompts, temperature settings, and model parameters. For example, [`plugins/docusign/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/docusign/agents/openai.yaml) supplies the system context:

```yaml
system: |
  You are a helpful assistant that interacts with Docusign's API.
  Use the provided endpoints to create envelopes and retrieve status.
temperature: 0.2
max_tokens: 1024

```

## How the Runtime Loads Your Plugin

When the OpenAI runtime initializes a plugin, it follows a specific sequence:

1. It reads [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to discover the OpenAPI definition and authentication requirements.
2. It loads [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) to apply runtime-specific configuration such as environment variable names.
3. UI components pull the icon from the `assets/` folder using the path declared in the manifest.
4. If the plugin offers a skill, the runtime registers the capability based on the `skills/` definition, making it callable via the chat interface.
5. Any agent behavior defined in `agents/` is instantiated when the plugin is invoked, allowing custom prompts or routing logic.

## Implementation Examples

Below are practical snippets demonstrating how to interact with the repository structure programmatically.

### Loading a Plugin Manifest

This Node.js example resolves and parses the Docusign plugin manifest:

```javascript
import fs from 'fs';
import path from 'path';

// Resolve the plugin's manifest
const manifestPath = path.resolve(
  __dirname,
  'plugins/docusign/.codex-plugin/plugin.json'
);
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log('Plugin name:', manifest.name);
console.log('OpenAPI spec URL:', manifest.api.url);

```

### Invoking a Skill via API

Assume the Docusign plugin contains a skill file at [`skills/create-envelope/SKILL.md`](https://github.com/openai/plugins/blob/main/skills/create-envelope/SKILL.md). A client invokes the skill through the OpenAI API:

```json
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Create a Docusign envelope for John Doe."
    }
  ],
  "plugins": [
    {
      "id": "docusign",
      "method": "create-envelope"
    }
  ]
}

```

The skill implementation reads from `plugins/docusign/skills/create-envelope/` to construct the appropriate API request.

## Summary

- **Place required metadata** in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and runtime settings in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) at the plugin root.
- **Store all static media** in the `assets/` directory and reference them with relative paths in the manifest.
- **Implement optional capabilities** by adding `skills/` for high-level actions and `agents/` for custom orchestration logic.
- **Follow the `plugins/<plugin-name>/` pattern** to ensure compatibility with the OpenAI platform and simplify maintenance.

## Frequently Asked Questions

### What is the purpose of .codex-plugin/plugin.json?

This file serves as the primary manifest declaring the plugin's metadata, OpenAPI specification URL, authentication type, and contact information. The OpenAI runtime reads this file first when loading your plugin to determine API capabilities and security requirements.

### How do I reference icons and logos in my plugin?

Specify the relative path from the plugin root in the `icon` field of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json). For example, `"icon": "assets/icon.png"` tells the runtime to look for the image at `plugins/<plugin-name>/assets/icon.png`.

### Can a plugin work without the skills/ or agents/ directories?

Yes. Both directories are optional. A basic plugin only requires [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), and an `assets/` folder with your icon. You only need `skills/` if exposing specialized high-level actions, and `agents/` if using custom model orchestration.

### Where should I store runtime configuration settings?

Store environment-specific settings and feature flags in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) at the plugin root. This file is distinct from the manifest and contains platform-specific configurations that the host reads during initialization.