How to Set Up Installation Policies for Plugins in OpenAI's Plugin Repository

To set up installation policies for plugins, define a policy object with allow_implicit_invocation in either the global plugin manifest (plugin.json) or skill-specific configuration (agents/openai.yaml), where skill-level settings override global defaults.

The openai/plugins repository implements a declarative policy system that governs how and when plugins may be invoked or installed. By configuring these policies, you control whether a skill can execute automatically or requires explicit user intent, preventing unintended side effects such as silent app installations.

Understanding the Policy Architecture

The installation policy system operates across three architectural layers: global manifests, skill-level overrides, and runtime enforcement.

Global Plugin Manifest

Every plugin contains a manifest file at plugins/<plugin-name>/.codex-plugin/plugin.json that defines default behaviors for all associated skills. The policy object at the top level of this JSON file establishes global rules.

{
  "name": "my-awesome-plugin",
  "display_name": "My Awesome Plugin",
  "description": "...",
  "policy": {
    "allow_implicit_invocation": false
  }
}

When allow_implicit_invocation is set to false, the system prevents automatic triggering of any skill belonging to this plugin unless the user explicitly requests it.

Skill-Level Policy Overrides

Individual skills can override global defaults through their configuration file at plugins/<plugin-name>/skills/<skill-name>/agents/openai.yaml. This YAML file takes precedence over the manifest for that specific skill.

interface:
  display_name: My Awesome Skill
policy:
  allow_implicit_invocation: false

The hierarchical precedence ensures that skill-level policies supersede global settings, allowing fine-grained control over sensitive operations while maintaining permissive defaults for other functions.

Runtime Enforcement Mechanism

During request routing, the OpenAI runtime checks the resolved policy value before executing a skill. If allow_implicit_invocation is false and the request lacks explicit user instruction, the runtime returns a policy_blocked error. This enforcement occurs independently of the installation recipes—markdown files like plugins/wix/skills/wix-manage/references/app-installation/install-wix-apps.md describe the technical steps for provisioning, but the policy gates whether those steps may be initiated implicitly.

How to Configure Installation Policies

Follow these steps to implement or modify installation policies in your plugin:

1. Define the global policy by editing plugins/<your-plugin>/.codex-plugin/plugin.json and adding the policy object with your desired allow_implicit_invocation value.

2. Override for specific skills by creating or editing plugins/<your-plugin>/skills/<skill-name>/agents/openai.yaml to include a policy block that refines the behavior for that particular skill.

3. Commit and deploy your changes. As a Git-based repository, openai/plugins applies policy updates automatically upon the next deployment cycle.

4. Validate the configuration by running the skill's test harness. Most skills include a tests/ directory where you can verify that implicit requests are rejected with the appropriate error code.

Real-World Examples from the Repository

Zoom Apps SDK: Explicit-Only Configuration

The Zoom Apps SDK skill demonstrates strict policy enforcement. In plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml, the configuration explicitly disables implicit invocation:

interface:
  display_name: Zoom Apps SDK
policy:
  allow_implicit_invocation: false

This ensures that Zoom applications cannot be installed or invoked by background processes or ambiguous user prompts. The policy acts as a safety gate, requiring clear user intent before executing any Zoom-related operations.

Wix App Installation Workflow

The Wix plugin manages third-party app installations through a multi-step recipe documented in plugins/wix/skills/wix-manage/references/app-installation/install-wix-apps.md. While this markdown file details the HTTP calls—including POST requests to https://www.wixapis.com/apps-installer-service/v1/app-instance/install—the actual execution permission depends on the policy defined in the skill's agents/openai.yaml.

By default, Wix installation skills set allow_implicit_invocation: false, ensuring that apps are only installed following explicit user commands rather than inferred intent. The policy file works in conjunction with the recipe: the policy determines whether the skill may run, while the recipe defines how the installation executes.

Summary

• Global policies reside in plugins/<plugin>/.codex-plugin/plugin.json and apply to all skills within that plugin.
• Skill-level overrides in plugins/<plugin>/skills/<skill>/agents/openai.yaml take precedence over global settings.
• The allow_implicit_invocation boolean controls whether a skill may execute without explicit user intent.
• Runtime enforcement occurs at the routing layer, returning policy_blocked errors for unauthorized implicit invocations.
• Installation recipes describe technical implementation but do not bypass policy restrictions.

Frequently Asked Questions

What is the difference between global and skill-level policies?

Global policies defined in .codex-plugin/plugin.json establish default behaviors for every skill in a plugin. Skill-level policies in agents/openai.yaml override these defaults for specific skills only. When both exist, the skill-level configuration takes precedence, allowing you to restrict sensitive operations while keeping general functions accessible.

How do I prevent a plugin from being installed implicitly?

Set allow_implicit_invocation: false in either the global manifest or the specific skill's agents/openai.yaml file. This flag forces the runtime to reject any request that lacks explicit user intent, blocking automatic or inferred installations. Verify the configuration by testing implicit invocations against your skill's endpoint.

Where are installation policies enforced in the OpenAI plugins runtime?

The runtime evaluates the resolved policy value during the request routing phase, immediately before dispatching to the skill handler. If the policy prohibits implicit invocation and the request context indicates automated or inferred triggering, the system returns a policy_blocked error without executing the skill's code.

Can I update policies without redeploying the plugin?

No. Because the openai/plugins repository uses a Git-based deployment model, policy changes require committing modifications to the relevant plugin.json or agents/openai.yaml files and triggering a new deployment. The runtime reads these configuration files during initialization, so updates only take effect after redeployment.

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