OpenAI Plugins: package examples, portable formats and connection boundaries
OpenAI plugin architecture: portable identity and OpenAI-specific overlays
Understand fixed portable component locations, the non-merging OpenAI overlay rule and why .app.json and MCP configuration represent different connections.
What you will learn
- Portable identity owns the package boundary
- The OpenAI extension replaces rather than merges the overlay
- Separate workflow instructions from connection wiring
Before you start
- Basic JSON and directory-path knowledge
- Understanding of skills and external-service permissions
Distinguish source examples from current format guidance and inspect a package without confusing metadata with runtime proof.
Key takeaways
- Portable identity and component locations remain canonical.
- An inline OpenAI object replaces the compatibility overlay wholesale.
- Connection configuration is not proof of an authenticated runtime.
Portable identity owns the package boundary
Current official guidance uses root plugin.json with an Agent Plugins schema as the portable entry point. Portable skills are discovered under skills and portable bundled MCP configuration under mcp.json. These fixed locations are not replaced or extended by a skills or mcpServers declaration in a Codex overlay.
Legacy examples without a recognized portable root use the compatibility manifest’s declarations. This is why simply moving the old file to the root is not a complete migration. The schema, component discovery and OpenAI-specific metadata placement must be reviewed together, while preserving the intended workflow.
The OpenAI extension replaces rather than merges the overlay
When extensions.com.openai is an object in a portable manifest, the official page says it supplies OpenAI-specific settings instead of the entire .codex-plugin/plugin.json overlay. The two are not merged. If that inline object is absent, the compatibility overlay can supply those settings while portable identity remains canonical.
This matters for partial migrations. An inline object containing only interface metadata does not automatically inherit apps or hooks from the old overlay. Review the complete selected settings object and test expected capabilities. A valid JSON document can still omit the connection a workflow needs.
Separate workflow instructions from connection wiring
In the Figma compatibility example, skills points to the workflow directory and apps points to .app.json, which maps a named integration to a registered connector identifier. The separate .mcp.json describes an endpoint and OAuth resource. Those are configuration observations, not proof that a host opens both connections or deduplicates them.
The teaching model in this series illustrates portable identity, fixed component locations and whole-object overlay selection. It excludes actual host loading, authentication, policy enforcement and tool execution. Use it to reason about migration mistakes, then validate the real package in the exact supported host you intend to use.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Identify portable versus compatibility-only layout.
- 2
Determine the single selected OpenAI settings object.
- 3
Check fixed component locations separately from overlay fields.
- 4
Test the resulting package in its intended host.
Copy-ready example
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "synthetic-notes",
"version": "0.1.0",
"description": "Synthetic notes exercise",
"extensions": {
"com.openai": {
"interface": {
"displayName": "Synthetic Notes"
}
}
}
}Frequently asked questions
Are inline and compatibility OpenAI settings merged?
No. The official page says an inline object replaces the entire overlay.
Can an overlay redirect portable skills discovery?
No. Recognized portable packages use the fixed skills and mcp.json locations.
Sources
- OpenAI Plugins / plugins/figma/.codex-plugin/plugin.jsonSource checked 2026-09-14
- OpenAI Plugins / plugins/figma/.app.jsonSource checked 2026-09-14
- OpenAI Plugins / plugins/figma/.mcp.jsonSource checked 2026-09-14
- OpenAI — Package your plugin (checked 2026-09-14)Source checked 2026-09-14