Common Path Format Mistakes in OpenAI Plugins: A Developer's Guide

Developers configuring OpenAI plugins must use POSIX-style forward-slash paths relative to the repository root in plugin.json and marketplace.json files; using Windows backslashes, absolute paths, or omitting the leading ./ causes the plugin loader to fail with "File not found" or validation errors.

The openai/plugins repository enforces a strict file-system layout where path formatting conventions determine whether skills are discoverable and executable. Understanding these OpenAI plugins path format requirements is essential because the orchestrator parses these values verbatim, and deviations result in broken asset resolution or complete plugin omission from the marketplace.

Why Path Formatting Matters

The plugin loader treats path strings literally, expecting POSIX-style, forward-slash paths that are relative to the repository root. When you specify paths incorrectly in .codex-plugin/plugin.json or .agents/plugins/marketplace.json, the system either rejects the configuration during validation or fails at runtime with mislocated assets and broken imports.

Seven Critical Path Format Mistakes

1. Using Windows Backslashes

The loader runs on Unix-based runtimes that do not interpret backslashes as separators. Using .\plugins\name causes the system to search for a literal filename containing backslash characters.

Symptom: "File not found" or "Unable to locate skill <name>".

Incorrect:

{
  "path": ".\\plugins\\magicpath"
}

2. Omitting the Leading ./

Paths without the ./ prefix are interpreted as absolute paths from the container filesystem root. Since /plugins/name does not exist in the container, the plugin is not discovered.

Symptom: Missing plugin in marketplace listings or "Unable to locate plugin" errors.

Incorrect:

{
  "path": "plugins/magicpath"
}

3. Providing Absolute Paths

Security policies restrict paths to the repository tree. Absolute paths such as /usr/local/plugins/name or C:/repo/plugins/name are explicitly rejected by the validator.

Symptom: Validation error: "Path must be relative to repository root".

Incorrect:

{
  "path": "/usr/local/plugins/magicpath"
}

4. Including Trailing Slashes

A trailing slash (./plugins/name/) results in double slashes when the runtime concatenates additional path components, breaking module resolution.

Symptom: Components cannot be imported; logs show module not found or path resolution errors.

5. Wrong Case Sensitivity

Filesystem case sensitivity differs between Windows (insensitive) and Linux/macOS (sensitive). Using ./Plugins/Figma instead of ./plugins/figma works locally on Windows but fails in production.

Symptom: Build failures on Linux/macOS that pass locally on Windows.

6. Embedding Spaces or Unusual Characters

While JSON parsers handle spaces correctly, the runtime may split paths on spaces when forming filesystem calls, causing argument parsing errors.

Symptom: Commands abort with "invalid argument" or "ambiguous path" errors.

7. Referencing Files Outside the Repo

Path traversal patterns like ../shared/utils violate security policies that forbid escaping the repository root.

Symptom: Loader throws "Path escapes repository" error during initialization.

Correct Path Implementation

Valid entries require forward slashes, the relative prefix, and no trailing slashes.

In plugins/magicpath/.codex-plugin/plugin.json:

{
  "name": "magicpath",
  "allowedTools": [
    "Bash(npx -y magicpath-ai *)"
  ],
  "path": "./plugins/magicpath"
}

In .agents/plugins/marketplace.json:

{
  "name": "magicpath",
  "path": "./plugins/magicpath"
}

Key Files Requiring Path Format Compliance

Audit these specific files in the openai/plugins repository to ensure your OpenAI plugins path format is correct:

• plugins/magicpath/.codex-plugin/plugin.json: Contains the canonical "path": "./plugins/magicpath" entry that demonstrates the required pattern.
• plugins/figma/.codex-plugin/plugin.json: Demonstrates correct relative path usage for the Figma plugin manifest.
• .agents/plugins/marketplace.json: The central index where a single typo in the path field hides an entire plugin from discovery; verify all entries follow the "path": "./plugins/<plugin>" convention.
• plugins/*/SKILL.md: Skill definitions referencing assets must use forward-slash separators when linking to supplementary files.

Summary

• Use POSIX-style forward slashes exclusively; never Windows backslashes.
• Prefix all paths with ./ to indicate they are relative to the repository root; never use absolute paths or parent traversal (../).
• Avoid trailing slashes to prevent double-slash concatenation errors that break module imports.
• Match case sensitivity exactly; test on Linux or macOS before deploying to prevent environment-specific failures.
• Validate paths in both individual plugin manifests (.codex-plugin/plugin.json) and the central marketplace index (.agents/plugins/marketplace.json).

Frequently Asked Questions

Why does my OpenAI plugin work on Windows but fail in CI/CD?

Windows filesystems are case-insensitive and accept backslashes, while Linux and macOS CI runners enforce case-sensitive POSIX paths. Update all paths to use lowercase directory names and forward slashes (./plugins/name) to ensure cross-platform compatibility.

Can I use absolute paths when developing locally?

No. The plugin loader explicitly forbids absolute paths for security reasons, as implemented in the openai/plugins validation logic. Even during local development, you must use relative paths starting with ./ from the repository root to prevent "Path must be relative to repository root" errors.

What happens if I forget the leading dot-slash in marketplace.json?

The system interprets plugins/my-plugin as an absolute path from the container filesystem root. Since /plugins/my-plugin does not exist in the container, the plugin loader cannot locate your skill, resulting in the plugin being omitted from the marketplace listing entirely.

Are trailing slashes ever acceptable in OpenAI plugin paths?

No. Trailing slashes cause the runtime to create double slashes when concatenating path components (e.g., ./plugins/foo/ + index.js becomes ./plugins/foo//index.js), which breaks module resolution and generates "module not found" errors in the orchestrator logs.

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