---
name: agent-plugin-authoring
description: Guide agents to author, review, and package Codex plugins with valid `.codex-plugin/plugin.json` manifests, optional skills, MCP servers, apps, scripts, assets, and marketplace metadata. Use when a user asks an agent to write a plugin, scaffold a local plugin, convert a workflow into a plugin, add skills to a plugin, prepare a plugin for sharing, or verify a plugin before installation.
---

# Agent Plugin Authoring

## Overview

Use this skill to guide another agent through creating a Codex plugin that is installable, reviewable, and easy to share. Prefer boring valid structure over clever automation; a plugin should be understandable from its manifest and directory layout.

## Authoring Workflow

1. Clarify the plugin purpose, target users, and expected invocation path.
2. Choose the smallest useful plugin surface:
   - `skills/` for reusable agent instructions.
   - `.mcp.json` plus server files for tool or MCP integrations.
   - `.app.json` plus app files for UI surfaces.
   - `scripts/` for deterministic helper commands used by skills or setup.
   - `assets/` for templates, icons, examples, or files copied into outputs.
3. Create the required plugin root and manifest:

```text
my-plugin/
|-- .codex-plugin/
|   `-- plugin.json
|-- skills/
|   `-- optional-skill/
|       `-- SKILL.md
|-- scripts/
|-- assets/
|-- .mcp.json
`-- .app.json
```

4. Fill metadata with real values. Do not leave placeholder markers in manifests or user-facing metadata.
5. Add only the companion directories and manifest references that actually exist.
6. Validate by inspecting JSON syntax, required files, relative paths, and install/update instructions.

## Manifest Rules

The required manifest lives at `.codex-plugin/plugin.json`. Keep the outer folder name and manifest `name` identical after normalization.

Use lowercase hyphen-case names:

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Short, concrete description of what this plugin provides."
}
```

When the plugin includes companion capabilities, add only the fields that match real files in the plugin:

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Short, concrete description of what this plugin provides.",
  "skills": ["skills/plugin-helper"],
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json"
}
```

Do not invent unsupported manifest fields. Do not list a skill, app, MCP file, script, or asset path until the file exists.

## Skill Content Inside Plugins

For each plugin skill:

- Create `skills/<skill-name>/SKILL.md`.
- Use YAML frontmatter with only `name` and `description` unless the runtime explicitly supports more.
- Make the description trigger-rich: include what the skill does and when to use it.
- Keep `SKILL.md` procedural and concise. Move long specs to `references/` only when they are conditionally needed.
- Reuse scripts for deterministic steps instead of asking future agents to rewrite fragile code.

Minimal skill:

```markdown
---
name: plugin-helper
description: Help agents perform a specific plugin-related workflow. Use when...
---

# Plugin Helper

Follow these steps...
```

## Marketplace Metadata

If the user wants the plugin to appear in a marketplace or share flow, create or update the marketplace entry separately from the plugin manifest. A local personal marketplace entry should include installation policy, authentication policy, and category:

```json
{
  "name": "my-plugin",
  "source": {
    "source": "local",
    "path": "./plugins/my-plugin"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}
```

Append entries by default. Reorder only when the user asks. Preserve existing marketplace display metadata.

## Validation Checklist

Before handing the plugin back:

- Confirm `.codex-plugin/plugin.json` exists and parses as JSON.
- Confirm manifest `name` matches the plugin folder name.
- Confirm every path referenced by the manifest exists.
- Confirm optional `.mcp.json` and `.app.json` parse as JSON when present.
- Confirm every bundled skill has a valid `SKILL.md` with `name` and `description`.
- Confirm no manifest or marketplace file contains placeholder text.
- Run any plugin-specific validation command that exists in the repository.
- Explain how to install or reload the plugin only after validation passes.

## Agent Guidance

When instructing another agent, give the target directory, desired plugin name, required surfaces, and validation command. Keep the request outcome-oriented:

```text
Use $agent-plugin-authoring to create a local Codex plugin named repo-helper in ./plugins.
It should include one skill for repository triage, no MCP server, and a marketplace entry.
Validate JSON files and summarize install steps.
```

If the user asks for a plugin but the repository already has a plugin scaffold script or a dedicated plugin creation skill, use that project-local tooling first and apply this skill as the review and structure guide.