# Understanding Skills and Apps Pointers in plugin.json for OpenAI Codex Plugins

> Learn how skills and apps pointers in plugin.json guide OpenAI Codex plugins. Discover where to find behavioral capabilities and UI configuration files.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-09-12

---

**The `skills` and `apps` pointers in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) tell the Codex platform where to find behavioral capabilities and UI configuration files, respectively.**

In the OpenAI plugins repository, every Codex plugin relies on a central manifest file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to declare its structure. These two specific fields act as relative path pointers that enable the platform to dynamically load action definitions and render embedded user interfaces. This convention appears consistently across all plugin implementations in the repository, including Zoom, Notion, Vercel, and Shopify.

## The `skills` Pointer: Defining Plugin Capabilities

The **`skills`** field points to a relative directory path containing the plugin's behavioral specifications.

In the Zoom plugin, this value is set to `"./skills/"`, which resolves to a directory containing individual skill packages. Each package includes a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file, executable scripts, and supporting assets that describe specific actions the plugin can perform. When Codex receives a user request, it parses these files to match intent against available capabilities like "search meetings" or "plan a product."

The platform consumes these definitions to resolve abstract requests into concrete operations, executing the defined logic through HTTP calls, local scripts, or server-side functions as specified in the skill files.

## The `apps` Pointer: Configuring the User Interface

The **`apps`** field points to a relative file path containing the plugin's presentation layer configuration.

According to the source code analysis, this typically references a file like `"./.app.json"` (as seen in the Zoom plugin). This JSON file contains UI-related metadata including menu definitions, icon assets, component layouts, and runtime settings that control how the plugin appears within the host application.

Codex reads this file to register UI components, expose entry points such as buttons in the chat interface, and provide assets referenced by the manifest including logos, composer icons, and screenshots. This registration enables the plugin to surface as a first-class application that users can launch directly from the Codex interface.

## Repository Conventions and Real-World Examples

The OpenAI plugins repository follows a strict convention where these pointers use relative paths from the plugin root.

In [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json), the configuration shows:

- **`skills`**: `"./skills/"` — referencing the directory at `plugins/zoom/skills/`
- **`apps`**: `"./.app.json"`` — referencing the configuration file at [`plugins/zoom/.app.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.app.json)

This pattern repeats across other official plugins like Notion, Vercel, and Shopify, confirming that **`skills`** tells Codex where to look for behavior definitions, while **`apps`** defines where to find presentation definitions.

## Loading and Resolving Paths Programmatically

When building tooling around these plugins, you must resolve the relative paths declared in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) to absolute system paths.

### Resolving Paths in Node.js

```javascript
import { readFileSync } from 'fs';
import path from 'path';

const pluginRoot = path.resolve('plugins/zoom');
const manifestPath = path.join(pluginRoot, '.codex-plugin', 'plugin.json');
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));

// Resolve absolute paths for the two pointers
const skillsDir = path.resolve(pluginRoot, manifest.skills); // → plugins/zoom/skills/
const appFile = path.resolve(pluginRoot, manifest.apps);     // → plugins/zoom/.app.json

```

### Discovering Skills in Python

```python
import json
import pathlib

root = pathlib.Path('plugins/zoom')
manifest = json.loads((root / '.codex-plugin' / 'plugin.json').read_text())

skills_path = root / manifest['skills']  # e.g., plugins/zoom/skills/

for skill_md in skills_path.glob('*/SKILL.md'):
    print(f'Found skill: {skill_md.parent.name}')

```

### App Configuration Structure

```json
{
  "name": "zoom",
  "components": [
    {
      "type": "button",
      "icon": "./assets/composer-icon.svg",
      "label": "Zoom"
    }
  ]
}

```

The Codex UI loader imports this configuration to register the plugin as an embeddable application.

## Summary

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** serves as the central manifest for every Codex plugin in the repository.
- The **`skills`** pointer references a directory containing [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files and scripts that define executable capabilities.
- The **`apps`** pointer references a JSON file (typically [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)) containing UI component definitions and runtime settings.
- Both fields use relative paths resolved against the plugin root directory.
- This dual-pointer system separates behavioral logic from presentation concerns, enabling Codex to load capabilities on-demand while rendering appropriate UI surfaces.

## Frequently Asked Questions

### What file format does the `apps` pointer reference?

The `apps` pointer references a JSON configuration file, conventionally named [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), that contains structured UI metadata. This file defines component layouts, icon assets, and entry points that the Codex platform uses to render the plugin interface within the host application.

### Can the `skills` pointer reference a single file instead of a directory?

No, the `skills` pointer must reference a relative directory path rather than an individual file. This directory contains multiple skill subdirectories, each housing a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file along with supporting scripts and assets. This structure allows Codex to discover and load multiple capabilities from a single plugin package.

### Where is the plugin.json file located in the repository?

The manifest file resides at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within each plugin's directory. For example, the Zoom plugin's manifest is located at [`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json) relative to the repository root.

### How does Codex determine which skill to execute for a user request?

Codex scans the directory referenced by the `skills` pointer and parses each [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file to understand available actions. It matches the semantic content of user requests against these skill descriptions to identify the appropriate capability, then loads and executes the associated logic defined in the skill's scripts or configuration.