skills/create-plugin/references/plugin-packages.md

# Standalone plugin packages

Use this format for skills-only plugins, connections to an existing MCP server,
and local plugins. Sites publishes its own canonical plugin; do not use this
account-upload flow to wrap a Site a second time.

## Author the files

Start from supplied source. For a new skills-only plugin, adapt
[`assets/starter-plugin/`](../assets/starter-plugin/); keep an existing app's source.

Use one self-contained directory with a lowercase kebab-case name of at most
64 characters, matching the root manifest's `name`:

```text
my-plugin/
  plugin.json
  skills/my-workflow/SKILL.md   # If the plugin provides instructions
  mcp.json                     # If it connects an MCP server
  assets/                      # Referenced assets, when needed
```

The root `plugin.json` uses Agent Plugins 1.0. For example:

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "The plugin's actual purpose.",
  "author": { "name": "Plugin author" },
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "My Plugin",
        "shortDescription": "A specific useful workflow",
        "longDescription": "Describe the implemented behavior.",
        "developerName": "Plugin author",
        "category": "Productivity",
        "capabilities": ["Interactive"],
        "defaultPrompt": "Help me with this workflow."
      }
    }
  }
}
```

Use a strict semantic version for a new plugin; preserve the existing version
scheme on updates. Each `skills/<name>/SKILL.md` needs matching
`name` and a `description` explaining when to use it in YAML frontmatter.
Put workflow instructions in the skill and conditional detail in references.

The listing subtitle, `extensions.com.openai.interface.shortDescription`, must
be at most 30 characters, counting spaces and punctuation.
Check its final length before packaging and rewrite it if necessary.

Plugin-level `defaultPrompt` accepts one string or an array of up to three
strings. Preserve their value, type, and order on edits. A skill's `agents/openai.yaml`
`interface.default_prompt` is a separate single-string field.

Portable clients discover `skills/` and `mcp.json` at fixed locations. Do not
add top-level `skills`, `mcpServers`, `apps`, or `interface` to the portable
manifest. For personal or workspace plugins, an existing app dependency uses
`.app.json` plus
`extensions.com.openai.apps: "./.app.json"`; use only verified app IDs.
If a local/older client requires `.codex-plugin/plugin.json`, retain that
compatibility overlay and synchronize its identity, version, and presentation
with the root manifest.

For public OpenAI directory uploads, exclude the root `.app.json` and all
non-null `apps` declarations, including `extensions.com.openai.apps` and
declarations in compatibility manifests even if shadowed. Use verified MCP
endpoints in portable `mcp.json` for required integrations. If only an existing
app binding is available, stop public packaging and explain that a supported
MCP endpoint is needed; do not invent one or silently drop functionality.
Prepare a separate upload copy, preserving the personal/workspace source and
bindings generated by the Developer Portal after MCP conversion in finalized
releases. Follow [public submission](../../prepare-plugin-submission/SKILL.md)
for the full export and dashboard flow; skip the account-save flow below.

For a remote MCP server, use its verified endpoint in portable `mcp.json`:

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "workflow-api": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}
```

Use the actual endpoint, transport, and authentication; use
[local plugins](local-plugins.md) for stdio servers.

Reuse or generate legible icons in `assets/`, referenced by contained relative
paths in `logo` and `composerIcon`. Use square PNG, JPEG, WebP, or SVG icons,
at least 48 × 48 pixels and no more than 5 MiB per file. Raster icons must not
exceed 4096 × 4096 pixels; transparent PNG is preferred. Include referenced
assets; exclude secrets, dependency directories, symlinks, and unrelated files.
Ask whether the creator wants optional dark-mode assets (`logoDark`,
`composerIconDark`) or brand colors (`brandColor`, `brandColorDark`), unless
their preference is already known. Do not require these fields or block
packaging when they are omitted; preserve existing values on updates.
For public submission, follow the
[app icon guidance](../../prepare-plugin-submission/references/listing.md#create-the-app-icon)
to help the creator make a missing icon and meet the submission requirements.

## Package

Create a ZIP or tar.gz containing the single plugin directory, including hidden
compatibility files. Write the archive outside that directory. Inspect its
manifest, skills, MCP configuration, and assets; run the target validator when
available. A source/ZIP-only request ends with the artifact, without upload.
If the package is being prepared for public submission, first follow
[submission preparation](../../prepare-plugin-submission/SKILL.md) to guide the
user through review and publication metadata. ZIP-only delivery does not skip
that preparation or remove metadata already supplied. Ordinary private exports
do not need submission materials.

## Save to the account

Use `create_plugin` to save a completed standalone package as a private plugin.
It accepts skills and MCP configurations, including remote servers, and uses
the authenticated user's active workspace when present, otherwise their
personal account. It does not deploy a server or submit a public listing.

If the request might refer to an existing plugin, follow
[update-plugin](../../update-plugin/SKILL.md) and its discovery guidance
before creating it. Resolve ambiguous matches before proceeding;
update the intended existing plugin rather than creating another.

Pass the absolute local archive path as `archive`; the host uploads the file.
Do not pass bytes, base64, URLs, or storage references. Do not create a placeholder
plugin to check connectivity, or repeat a successful or uncertain creation.
If unavailable, preserve the package and report saving as pending; use an
authorized local install flow when applicable.

After success, return a clickable link using the tool's `plugin_url`. Label it
with the submitted manifest's human-readable `displayName`, not the returned
internal package name; use `View plugin` if no display name is present. Treat
the label as plain text: replace newlines with spaces and escape its Markdown
punctuation, including existing backslashes. Keep the exact plugin and release
IDs for later edits. Creation alone does not prove that an attached server or
UI works; verify the requested behavior after installation/connection.