# How to Specify the Path Format for OpenAI Plugins: Syntax and Examples

> Learn how to correctly specify the path format for OpenAI plugins using POSIX-style relative paths and forward slashes in your plugin.json manifest for cross-platform compatibility.

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

---

**OpenAI plugins require POSIX-style relative paths starting with `./` and using forward slashes for every file reference in the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest to ensure cross-platform compatibility and security sandboxing.**

The `openai/plugins` repository enforces a strict path format for OpenAI plugins that governs how the runtime loader resolves file references. Every path declared in the plugin manifest must be relative to the plugin root, use forward slashes exclusively, and begin with an explicit `./` prefix. Following these conventions ensures your plugin functions correctly across Windows, macOS, and Linux environments without resolution errors.

## Manifest Path Requirements

In the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, the runtime loader resolves all file references from the plugin's root directory—the folder containing the `.codex-plugin` subdirectory. Any deviation from the relative path format causes the loader to fail to locate the target files.

### Apps and Interface Assets

The optional `apps` field must reference its configuration using a relative path such as `"./.app.json"`. Asset fields including `interface.logo` and `interface.composerIcon` must point to bundled files using repository-relative paths like `"./assets/logo.png"`.

### Skills and Hooks Arrays

For skills and hooks that reference external configuration files, the same relative path rules apply. Any JSON or YAML file referenced in these arrays must be reachable via a relative URL starting with `./` and using forward slashes exclusively.

## Architectural Design of Path Resolution

The OpenAI plugin loader uses Node.js's `path` API to normalize all file references. This architecture ensures consistent behavior across operating systems while maintaining strict security boundaries.

### Repository-Relative Resolution

The loader constructs absolute paths by joining the plugin root directory with the manifest-provided relative string. This design allows the same plugin to be checked out at any disk location or deployed in a container without rewriting absolute paths.

### Cross-Platform Normalization

By enforcing forward-slash separators, the runtime works uniformly on all platforms. The underlying Node.js `path` library handles normalization, but the manifest must provide the POSIX-style format to avoid platform-specific interpretation errors.

### Security Sandboxing

The loader explicitly rejects any path attempting to escape the plugin root, such as `"../some/secret.txt"`. This prevents malicious manifests from accessing files outside the plugin sandbox, ensuring that all file operations remain confined to the plugin directory.

## Valid Path Format Examples

The Attio plugin in [`plugins/attio/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/attio/.codex-plugin/plugin.json) demonstrates the canonical format:

```json
{
  "apps": "./.app.json",
  "interface": {
    "composerIcon": "./assets/logo.png",
    "logo": "./assets/logo.png"
  }
}

```

When defining agents or skills in YAML files, maintain the same relative format:

```yaml
agents:
  - name: "example-agent"
    file: "./agents/example-agent.yaml"

```

The runtime loads these manifests by joining the plugin root with the relative path:

```javascript
const path = require('path');
const pluginRoot = __dirname; // e.g., /repo/plugins/example
const manifestPath = path.join(pluginRoot, './.codex-plugin/plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

```

## Key Reference Files

Several files in the repository establish these path conventions:

- **[`plugins/attio/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/attio/.codex-plugin/plugin.json)**: Shows the canonical `./` prefixed relative paths for `apps` and asset fields.
- **[`plugins/zoom/skills/zoom-apps-sdk/references/marketplace-apps.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/references/marketplace-apps.md)**: Demonstrates how API endpoints reference manifests via relative URIs.
- **[`plugins/figma/skills/figma-use/references/plugin-api-standalone.d.ts`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-use/references/plugin-api-standalone.d.ts)**: Illustrates path format requirements for SVG path strings.

## Summary

- **Use forward slashes** (`/`) exclusively; never use backslashes.
- **Start every path with `./`** to denote repository-relative references explicitly.
- **Keep all file references inside the plugin directory**; escaping via `../` is blocked for security.
- **Reference the Attio plugin implementation** at [`plugins/attio/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/attio/.codex-plugin/plugin.json) for canonical examples.

## Frequently Asked Questions

### Can I use absolute paths in OpenAI plugin manifests?

No. The runtime loader rejects absolute paths and requires all file references to be relative to the plugin root directory using the `./` prefix. Absolute paths would break portability across different environments and deployment locations.

### Why does my plugin fail to load on Windows?

If you use backslashes (`\`) or omit the `./` prefix, the Node.js path normalization may fail to resolve the file correctly on Windows systems. Always use forward slashes and explicit relative prefixes to ensure cross-platform compatibility as implemented in the `openai/plugins` repository.

### Can I reference files outside the plugin directory using `../`?

No. The loader explicitly rejects paths containing `../` or any traversal sequences that would escape the plugin root. This security measure prevents unauthorized file access outside the plugin sandbox.

### Is the `./` prefix mandatory for all paths?

While the loader may resolve simple filenames in some contexts, the specification requires the explicit `./` prefix for readability and to avoid ambiguity with built-in module names. All official plugins in the repository consistently use this format for every file reference.