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

The skills and apps pointers in .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 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 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, 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 to absolute system paths.

Resolving Paths in Node.js

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

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

{
  "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 serves as the central manifest for every Codex plugin in the repository.
• The skills pointer references a directory containing SKILL.md files and scripts that define executable capabilities.
• The apps pointer references a JSON file (typically .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, 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 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 within each plugin's directory. For example, the Zoom plugin's manifest is located at 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 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.

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