What Makes an OpenAI Plugin “Simpler”: 5 Patterns from the Reference Implementation

A simpler OpenAI plugin minimizes its manifest to only essential metadata, implements single-purpose skills with plain HTTP/JSON, and chooses the most straightforward operational path—such as webhooks over persistent sockets—to reduce complexity and runtime footprint.

The openai/plugins repository demonstrates that plugin simplicity is an intentional architectural choice that reduces validation overhead, limits failure modes, and accelerates development cycles. A simple OpenAI plugin adheres to a minimal footprint across its manifest configuration, skill boundaries, and runtime dependencies. By analyzing the Figma, Zoom, Vercel, and Temporal reference implementations, we identify the specific technical patterns that define simplicity in this framework.

1. Minimal Manifest Metadata

The foundation of a simple OpenAI plugin is a stripped-down .codex-plugin/plugin.json that declares only the fields the platform strictly requires. In plugins/figma/.codex-plugin/plugin.json, the manifest contains solely the core properties: name, version, description, interface, skills, and apps.

Omitting optional capabilities, extra assets, or complex versioning schemes eliminates unnecessary validation logic and runtime checks. Every additional key in the manifest generates potential points of failure, so simpler plugins resist declaring speculative features.

{
  "name": "my-simple-plugin",
  "version": "0.0.1",
  "description": "A minimal example plugin.",
  "interface": {
    "displayName": "Simple",
    "shortDescription": "Does one thing, does it well.",
    "category": "Utility",
    "capabilities": ["Read", "Write"]
  },
  "skills": "./skills/",
  "apps": "./.app.json"
}

2. Atomic Skill Architecture

Complexity arises when a skill attempts to orchestrate multiple unrelated tasks. A simpler OpenAI plugin structures each skill as an atomic, self-contained unit focused on one concrete objective.

Each skill directory contains a concise SKILL.md file, a minimal set of reference files, and a single script that directly invokes the target API. The Figma plugin exemplifies this through its defaultPrompt, which lists three short, high-level actions—each satisfied by a discrete skill without multi-stage pipelines.

# Simple Text Sender

**Goal** – Send a short text message using Twilio.

**Prompt**  
`Send a simple text message to +15551234567 with the body "Hello!"`

**Reference** – Twilio REST API expects a JSON payload:

```json
{
  "to": "+15551234567",
  "from": "+15557654321",
  "body": "Hello!"
}

Script (Python)

import requests, os

def run():
    payload = {
        "to": "+15551234567",
        "from": os.getenv("TWILIO_FROM"),
        "body": "Hello!"
    }
    resp = requests.post(
        "https://api.twilio.com/2010-04-01/Accounts/{SID}/Messages.json",
        data=payload,
        auth=(os.getenv("TWILIO_SID"), os.getenv("TWILIO_TOKEN"))
    )
    return resp.json()

## 3. Plain HTTP/JSON Runtime Choices

Runtime simplicity requires bypassing custom wrappers, proxies, and large client libraries in favor of raw HTTP requests and JSON payloads. According to [`plugins/vercel/skills/ai-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md), using a plain `"provider/model"` string is explicitly documented as the simplest approach, whereas introducing a proxy wrapper adds unnecessary complexity and risks breaking existing tooling.

Similarly, [`plugins/temporal/skills/temporal-developer/references/typescript/data-handling.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/typescript/data-handling.md) recommends JSON serialization as the default because it is “simpler and more performant” than Protobuf for most TypeScript use cases. This approach minimizes the dependency graph and reduces potential failure surfaces.

## 4. Simplified Operational Delivery

Operational simplicity means selecting the most straightforward delivery mechanism that meets latency requirements. When persistent, low-latency connections are unnecessary, webhooks provide a simpler alternative to WebSockets or gRPC.

The Zoom plugin illustrates this trade-off in [`plugins/zoom/skills/websockets/RUNBOOK.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/websockets/RUNBOOK.md), where the documentation explicitly recommends using a webhook instead of the more complex WebSocket implementation unless real-time delivery is strictly required. This decision eliminates the infrastructure overhead of maintaining persistent socket connections.

```bash

# Webhook (simplest)

curl -X POST https://my-plugin.example.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"event":"message","payload":{...}}'

Summary

• A simpler OpenAI plugin contains only essential metadata in .codex-plugin/plugin.json, specifically name, version, description, interface, skills, and apps.
• Each skill is self-contained with a single SKILL.md file describing one concrete task, minimal reference files, and a direct API call script.
• Plain HTTP/JSON is preferred over heavy SDKs, custom proxies, or complex serialization formats like Protobuf.
• Webhooks and simple polling are favored over WebSockets or gRPC unless low-latency persistence is mandatory.
• Concise defaultPrompt values in the manifest prevent interface bloat and keep the plugin focused on core use cases.

Frequently Asked Questions

What fields are required for a simple OpenAI plugin manifest?

A minimal manifest in .codex-plugin/plugin.json requires only six top-level properties: name, version, description, interface, skills, and apps. The Figma reference implementation at plugins/figma/.codex-plugin/plugin.json demonstrates this exact configuration, omitting optional capabilities and complex versioning schemes to reduce validation overhead.

Should I use WebSockets or webhooks for my OpenAI plugin?

Choose webhooks when low-latency, persistent delivery is not a strict requirement. According to plugins/zoom/skills/websockets/RUNBOOK.md, webhooks provide the simplest operational path that eliminates the infrastructure complexity of maintaining persistent socket connections, making them the preferred default for most use cases.

How do I keep my OpenAI plugin's dependencies minimal?

Avoid custom wrappers, proxies, and large client libraries. Instead, use raw HTTP requests with JSON payloads, as recommended in plugins/vercel/skills/ai-sdk/SKILL.md. This approach, also favored by the Temporal plugin for data serialization, minimizes the dependency graph and reduces potential failure modes.

What defines a "single-purpose" skill in the OpenAI plugins framework?

A single-purpose skill contains exactly one SKILL.md file describing a concrete task, a minimal set of reference files, and a single script that directly calls the target API without multi-stage pipelines. The skill's prompt should address one high-level action, similar to the discrete actions listed in the Figma plugin's defaultPrompt.

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