# What Supporting Files Does a Codex Plugin Include? Complete File Structure Guide

> Explore the supporting files for a Codex plugin, including SKILL.md documentation, YAML configs, scripts, tests, and deployment metadata. Understand the complete file structure.

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

---

**A Codex plugin requires a structured ecosystem of supporting files—including SKILL.md documentation, YAML agent configurations, implementation scripts, tests, and deployment metadata—to be self-describing, testable, and deployable across various runtimes.**

While every Codex plugin starts with a [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest, production-ready plugins in the **openai/plugins** repository include a comprehensive set of supporting files that enable the LLM to understand, test, and execute skills reliably. These files range from human-readable documentation and agent prompts to executable scripts and dependency manifests.

## Core Manifest and Visual Assets

The entry point for any plugin is the **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** file located in the `.codex-plugin/` directory. This manifest declares the plugin's metadata, version, and the relative path to its skills.

For example, in [`zotero/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/zotero/.codex-plugin/plugin.json), the manifest specifies:

- The plugin name and description
- The skills directory location (`"skills": "./skills/"`)
- UI assets such as the composer icon

Visual identity files reside in an **`assets/`** folder. The manifest references these via fields like `"composerIcon": "./assets/icon.png"`, allowing the Codex UI to display branding consistently. The Zotero plugin includes `zotero/assets/icon.png` for this purpose.

## Skill Documentation and Definitions

Each skill requires a **[`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)** file that serves as human-readable documentation describing the skill's purpose, usage examples, and expected inputs/outputs. This file lives inside the skill-specific subdirectory, such as [`zotero/skills/zotero/SKILL.md`](https://github.com/openai/plugins/blob/main/zotero/skills/zotero/SKILL.md).

The SKILL.md acts as the primary contract between the developer and the LLM, explaining what the skill can do before any code is executed.

## LLM Agent Configuration

Inside the skill directory, the **`agents/`** folder contains YAML configuration files that define how the LLM should behave when invoking the skill. These files specify system prompts, temperature settings, and available tools.

For instance, [`zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/zotero/skills/zotero/agents/openai.yaml) contains the system message and parameters:

```yaml
system: |
  You are a Zotero assistant. Use the API described in
  {{reference_path}} to search the user's library.
variables:
  reference_path: "../references/local-api-routes.md"

```

This configuration allows the LLM to reference technical documentation dynamically during execution.

## Reference Documentation

The **`references/`** directory holds in-depth technical specifications that aid both developers and the LLM. Unlike SKILL.md, these files contain detailed API endpoint tables, route definitions, or design rationales.

The Zotero plugin includes [`zotero/skills/zotero/references/local-api-routes.md`](https://github.com/openai/plugins/blob/main/zotero/skills/zotero/references/local-api-routes.md), which the agent YAML can reference to ensure accurate API usage without hardcoding specifications into the prompt itself.

## Implementation Scripts

The actual executable code resides in the **`scripts/`** directory. These files perform the skill's work—making API calls, processing data, or interacting with external services.

The Zotero plugin implements its core logic in [`zotero/skills/zotero/scripts/zotero.py`](https://github.com/openai/plugins/blob/main/zotero/skills/zotero/scripts/zotero.py). Scripts can be written in Python (`.py`), JavaScript (`.js`), or TypeScript (`.ts`), depending on the runtime requirements.

To load configuration from the manifest at runtime, scripts can use:

```python
import json
import pathlib

PLUGIN_ROOT = pathlib.Path(__file__).resolve().parents[2]
with open(PLUGIN_ROOT / ".codex-plugin" / "plugin.json") as f:
    manifest = json.load(f)

icon_path = PLUGIN_ROOT / manifest["interface"]["composerIcon"]
print(f"Plugin icon located at: {icon_path}")

```

## Testing and Validation Assets

Reliable plugins include comprehensive test suites in a **`tests/`** directory. These validate skill behavior and contract compliance before deployment.

The Google Calendar plugin demonstrates this with [`google-calendar/tests/test_google_calendar_plugin_contract.py`](https://github.com/openai/plugins/blob/main/google-calendar/tests/test_google_calendar_plugin_contract.py), which ensures the plugin adheres to its declared interface.

**Fixtures** in a **`fixtures/`** directory provide mock data for testing without requiring live external services. The [`plugin-eval/fixtures/minimal-skill/SKILL.md`](https://github.com/openai/plugins/blob/main/plugin-eval/fixtures/minimal-skill/SKILL.md) example shows how minimal test data can validate skill loading and parsing.

## Runtime Dependencies

Plugins declare their external libraries through standard dependency files:

- **[`package.json`](https://github.com/openai/plugins/blob/main/package.json)** for Node.js projects (e.g., [`product-design/templates/prototype/package.json`](https://github.com/openai/plugins/blob/main/product-design/templates/prototype/package.json))
- **[`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt)** or **[`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml)** for Python projects

These files ensure the runtime environment can install necessary packages before executing the plugin's scripts. To inspect dependencies programmatically:

```js
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
console.log('Dependencies:', Object.keys(pkg.dependencies));

```

## Deployment and Hosting Metadata

Finally, **[`hosting.json`](https://github.com/openai/plugins/blob/main/hosting.json)** files and **`.openai/`** directories describe deployment configurations, specifying platforms like Vercel or Cloudflare Workers and required build steps.

For example, [`product-design/templates/prototype/.openai/hosting.json`](https://github.com/openai/plugins/blob/main/product-design/templates/prototype/.openai/hosting.json) defines how the plugin should be hosted and packaged for distribution.

## Summary

Supporting files transform a simple manifest into a complete, deployable Codex plugin:

- **Manifest** ([`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)): Declares metadata and skill locations in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)
- **Assets** (`icon.png`, etc.): Provide visual identity for the UI
- **Skill Docs** ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)): Human-readable skill descriptions in `skills/{name}/SKILL.md`
- **Agent Configs** (`agents/*.yaml`): Control LLM behavior and prompts
- **References** (`references/*.md`): Technical specifications for API usage
- **Scripts** (`scripts/*`): Executable implementation code in Python, JavaScript, or TypeScript
- **Tests** (`tests/*`): Validate contract compliance and functionality
- **Fixtures**: Mock data for isolated testing in `fixtures/`
- **Dependencies** ([`package.json`](https://github.com/openai/plugins/blob/main/package.json), [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt)): Declare runtime requirements
- **Hosting** ([`hosting.json`](https://github.com/openai/plugins/blob/main/hosting.json)): Define deployment infrastructure in [`.openai/hosting.json`](https://github.com/openai/plugins/blob/main/.openai/hosting.json)

## Frequently Asked Questions

### What is the difference between SKILL.md and reference documentation?

**SKILL.md** provides a high-level overview of what a skill does, including usage examples and intended functionality, while **reference documentation** in the `references/` folder contains granular technical details like API endpoint specifications. The SKILL.md is typically consumed by developers and the LLM for understanding capability, whereas reference files are often templated into agent prompts for precise execution details.

### How do agent YAML files control LLM behavior?

Agent YAML files in the `agents/` directory define the **system prompt**, **temperature**, and **variables** that configure the LLM's behavior when invoking a specific skill. For example, [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) can specify that the model should act as a "Zotero assistant" and reference specific API documentation variables, ensuring consistent and contextually appropriate responses.

### Where should I place plugin tests?

Tests should reside in a **`tests/`** directory at the plugin root or within specific skill folders. Following the pattern in [`google-calendar/tests/test_google_calendar_plugin_contract.py`](https://github.com/openai/plugins/blob/main/google-calendar/tests/test_google_calendar_plugin_contract.py), these files should validate that the skill adheres to its declared contract. Use **fixtures** in a `fixtures/` directory to provide mock data, allowing tests to run without dependencies on live external services.

### What files are required for deploying a Codex plugin?

At minimum, deployment requires the **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** manifest and the **implementation scripts**. However, production deployments typically also need **dependency files** (like [`package.json`](https://github.com/openai/plugins/blob/main/package.json) or [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt) to install runtime libraries) and **hosting metadata** (such as [`.openai/hosting.json`](https://github.com/openai/plugins/blob/main/.openai/hosting.json)) to specify build steps and hosting platforms like Vercel or Cloudflare Workers.