# How Codex Plugins Are Documented in the OpenAI Plugins Repository

> Discover how Codex plugins are documented in the OpenAI plugins repository. Explore JSON manifests, markdown specifications, and verification scripts for clear metadata and safe invocation.

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

---

**TLDR:** Codex plugins are documented using a hierarchical per-plugin structure consisting of a JSON manifest, markdown skill specifications, reference assets, and executable verification scripts that define both the plugin metadata and the safe invocation workflow.

The `openai/plugins` repository implements a strict documentation protocol that ensures the Codex runtime and human developers can understand plugin capabilities. This architecture separates metadata from implementation details, enabling the Codex marketplace to surface plugins while providing detailed execution guidance. Understanding how Codex plugins are documented requires examining five distinct components that work together across the repository.

## The Five Layers of Codex Plugin Documentation

Each plugin in the repository follows a consistent documentation hierarchy that spans from repository-level overviews to executable verification scripts.

### Repository Entry Point (README.md)

The **top-level overview** lives in [`README.md`](https://github.com/openai/plugins/blob/main/README.md) at the repository root. This file introduces the general purpose of the repository, explains how plugins are organized, and points to the default marketplace configuration at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). It serves as the entry point for developers navigating the plugin ecosystem.

### Plugin Manifest ([`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json))

Every plugin contains a **plugin manifest** located at `<plugin>/.codex-plugin/plugin.json` (e.g., [`plugins/box/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/box/.codex-plugin/plugin.json)). This JSON file defines the plugin name, version, description, author, and entry points (`skills/`, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)). The manifest also contains the UI and interface description shown in the Codex marketplace, allowing the runtime to locate the `skills/` directory and surface the plugin in the UI.

### Skill Specifications ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md))

The **primary source of truth** for plugin invocation is the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file located at `<plugin>/skills/<skill>/SKILL.md` (e.g., [`plugins/box/skills/box/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/SKILL.md)). This markdown file provides a high-level description of the skill's purpose and contains a step-by-step workflow. It enumerates required API calls, defines guardrails for safe execution, and specifies verification steps that must pass before the plugin performs any action.

### Reference Documentation (`references/`)

**Supplemental assets** reside in `<plugin>/skills/<skill>/references/` (e.g., [`plugins/box/skills/box/references/auth-and-setup.md`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/references/auth-and-setup.md)). These markdown files contain detailed API documentation, request and response examples, authentication guides, and troubleshooting notes. The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) links to these references for deep technical details without cluttering the primary workflow description.

### Verification Scripts (`scripts/`)

**Executable helpers** are stored in `<plugin>/skills/<skill>/scripts/` (e.g., [`plugins/box/skills/box/scripts/box_cli_smoke.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_cli_smoke.py)). These are small Python or shell scripts used for local verification or CLI-based smoke tests. While mentioned in the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) verification steps, they serve as optional utilities that validate authentication and basic functionality before the Codex engine executes the full skill workflow.

## Runtime Documentation Flow

When the Codex runtime loads a plugin, it follows a specific architectural flow to consume the documentation:

1. **README.md** introduces the repository structure and points to the marketplace configuration.

2. The **manifest JSON** is read to surface the plugin in the marketplace UI and locate the `skills/` directory entry point.

3. Inside `skills/`, the **SKILL.md** is parsed as the authoritative guide, providing the workflow, guardrails, and verification commands.

4. **Reference** markdown files are accessed when the runtime or developer needs deep API specifications or troubleshooting context.

5. **Scripts** are executed during verification steps (e.g., running [`box_cli_smoke.py`](https://github.com/openai/plugins/blob/main/box_cli_smoke.py) to check authentication status).

This flow ensures that both the Codex engine and developers understand **what** a plugin does, **how** to call it, and **what** safety checks to run before performing any action.

## Parsing Codex Plugin Documentation Programmatically

You can consume the documentation structure using standard file parsing. The manifest provides metadata, while the skill markdown contains the executable logic.

Load the plugin manifest to extract entry points and metadata:

```python
import json
import pathlib

# Load a plugin's manifest (example: the Box plugin)

manifest_path = pathlib.Path(
    "/cache/repos/github.com/openai/plugins/main/plugins/box/.codex-plugin/plugin.json"
)
with manifest_path.open() as f:
    manifest = json.load(f)

print("Plugin:", manifest["name"])
print("Description:", manifest["description"])
print("Skills folder:", manifest["skills"])

```

Parse the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) to extract workflow steps and sections:

```python

# Example of parsing a SKILL.md file to extract the workflow steps

skill_path = pathlib.Path(
    "/cache/repos/github.com/openai/plugins/main/plugins/box/skills/box/SKILL.md"
)
steps = []
with skill_path.open() as f:
    for line in f:
        if line.lstrip().startswith("## "):

            steps.append(line.strip('# \n'))

print("Skill sections:", steps)

```

Execute verification scripts referenced in the skill documentation:

```bash

# Run the verification script referenced in the Box skill

python3 plugins/box/skills/box/scripts/box_cli_smoke.py check-auth

```

These snippets demonstrate how tooling interacts with the documentation: the manifest is parsed for metadata, the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) is inspected for workflow sections, and the referenced scripts are executed as part of the verification process.

## Summary

- **Codex plugins** are documented per-plugin using a consistent five-layer structure: repository README, JSON manifest, SKILL.md, reference assets, and verification scripts.
- The **plugin manifest** at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) defines metadata and entry points consumed by the Codex marketplace.
- **SKILL.md** serves as the authoritative source for workflow steps, guardrails, and verification commands.
- **Reference documentation** in the `references/` directory provides deep API details and troubleshooting guides linked from the primary skill specification.
- **Verification scripts** in the `scripts/` directory enable automated safety checks before plugin execution.

## Frequently Asked Questions

### What is the purpose of the plugin.json manifest?

The [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest file defines the plugin's metadata—including name, version, description, author, and entry points—that the Codex runtime uses to surface the plugin in the marketplace UI and locate the `skills/` directory. It acts as the machine-readable entry point for plugin discovery and loading.

### How does SKILL.md differ from reference documentation?

[`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) contains the primary high-level description of a skill's purpose, step-by-step workflow, and execution guardrails, making it the authoritative guide for how a skill should be invoked. Reference documentation in the `references/` directory provides supplemental deep-dive technical details, such as API specifications and authentication setup, that are linked from but separate from the main workflow.

### Where are verification scripts located in a Codex plugin?

Verification scripts reside in `<plugin>/skills/<skill>/scripts/` (e.g., [`plugins/box/skills/box/scripts/box_cli_smoke.py`](https://github.com/openai/plugins/blob/main/plugins/box/skills/box/scripts/box_cli_smoke.py)). These executable files are referenced in the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) verification steps and are used to run smoke tests or authentication checks before the Codex engine executes the full skill workflow.

### Is the documentation structure consistent across all OpenAI plugins?

Yes, all plugins in the `openai/plugins` repository follow the same documentation structure. Each plugin contains a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest, a `skills/` directory with [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files, optional `references/` documentation, and optional `scripts/` verification utilities, ensuring uniform discoverability and interaction patterns across the ecosystem.