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

OpenAI plugins require POSIX-style relative paths starting with ./ and using forward slashes for every file reference in the .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 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 demonstrates the canonical format:

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

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

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

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: Shows the canonical ./ prefixed relative paths for apps and asset fields.
• 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: 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 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.

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