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

> Avoid common path format mistakes in OpenAI plugins. Learn to use POSIX paths correctly in plugin.json and marketplace.json to prevent file not found errors and ensure smooth plugin loading.

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

---

**Developers configuring OpenAI plugins must use POSIX-style forward-slash paths relative to the repository root in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and [`marketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) or [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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:

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

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

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/magicpath/.codex-plugin/plugin.json):

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

```

In [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json):

```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`](https://github.com/openai/plugins/blob/main/plugins/magicpath/.codex-plugin/plugin.json)**: Contains the canonical `"path": "./plugins/magicpath"` entry that demonstrates the required pattern.
- **[`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json)**: Demonstrates correct relative path usage for the Figma plugin manifest.
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)) and the central marketplace index ([`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/index.js) becomes [`./plugins/foo//index.js`](https://github.com/openai/plugins/blob/main/./plugins/foo//index.js)), which breaks module resolution and generates "module not found" errors in the orchestrator logs.