/cao-agent-plugin-creator

name: cao-agent-plugin-creator
description: Author a new Agent Plugins 1.0.0 package from an empty directory - write the plugin.json manifest, lay out skills/, optionally add an mcp.json, and check the result with CAO's own validator. Use when the user says "create an Agent Plugin", "scaffold a plugin.json", "package these skills as an Agent Plugin", "which keys does the manifest need", "why is my plugin.json rejected", or "add an mcp.json to my package". States the manifest contract from the schema bytes CAO vendors and pins, and the Agent Skills limits CAO's loader does not check. Not for CAO event plugins, the Python packages that react to cao-server lifecycle events (use cao-plugin). Not for migrating an existing client-specific agent plugin to the portable structure (use migrate-agent-plugin). Not for auditing an existing Agent Plugin package against the limits (use cao-agent-plugin-audit).

Create an Agent Plugin

Take a contributor from an empty directory to an Agent Plugins 1.0.0 package that CAO's own validator reports as loadable. Every rule below is read from the schema bytes CAO vendors, or from CAO's validator code, and each one names its source so you can check it rather than trust it.

Two unrelated things share the word "plugin"

CAO has two systems that both use the word. Never write it unqualified.

| Term | What it is | Where it lives in CAO | |---|---|---| | **Agent Plugin** | A portable directory of Agent Skills, optionally with MCP servers, described by a `plugin.json` manifest | `src/cli_agent_orchestrator/agent_plugins/`, `docs/agent-plugins.md` | | **event plugin** | A Python package running inside `cao-server`, reacting to lifecycle events | `src/cli_agent_orchestrator/plugins/`, `docs/plugins.md` | | **Agent Skill** | A directory holding a `SKILL.md`; the unit an Agent Plugin ships | `skills/`, `docs/skills.md` |

This skill is about the first row only. For an event plugin, load `cao-plugin`. To convert an agent plugin that already exists for one client, load `migrate-agent-plugin`; this skill starts from nothing.

The smallest valid package

An Agent Plugin root needs exactly one file:

my-package/
└── plugin.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-package"
}

That manifest is complete. Everything else is optional. A package that ships skills adds a `skills/` directory:

my-package/
├── plugin.json
├── mcp.json                 # optional
└── skills/                  # optional
    ├── first-skill/
    │   └── SKILL.md
    └── second-skill/
        ├── SKILL.md
        └── references/      # anything inside a skill directory is the skill's own business
            └── notes.md

The manifest contract

The authority is the vendored schema, `src/cli_agent_orchestrator/schemas/agent_plugins/1.0.0/plugin.schema.json`. Line numbers below are into that file.

Required keys: `$schema` and `name`, nothing else

`"required": ["$schema", "name"]` (`:63`). Those two keys are the whole required set. A manifest with only them is valid.

• **`$schema`** must be exactly the string

`https://agent-plugins.org/schemas/1.0.0/plugin.schema.json` (a `const`, `:8-11`). It is an identifier, not a download location; see "Vendored bytes" below.

• **`name`** is a string of **1 to 64 characters** (`minLength`, `maxLength`,

`:14-15`) matching this pattern (`:16`):

  ^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$

In words: lowercase ASCII letters, digits, `.` and `-`; it starts and ends with a letter or digit; and it never contains `--` or `..`.

| `name` value | Valid? | Why | |---|---|---| | `my-package` | yes | | | `tools.v2` | yes | `.` is allowed inside the name | | `a` | yes | one character is within 1-64 | | `My-Package` | no | uppercase | | `-tools` | no | starts with `-` | | `tools-` | no | ends with `-` | | `my--tools` | no | contains `--` | | `my..tools` | no | contains `..` | | `my_tools` | no | `_` is not in the character set |

Optional keys

These are the only other keys the schema defines (`:19-61`):

| Key | Type | |---|---| | `version` | string | | `description` | string | | `author` | object with only `name`, `email`, `url`, all strings; closed (`:25-39`) | | `homepage` | string | | `repository` | string | | `license` | string | | `keywords` | array of strings | | `extensions` | object whose every member is an object, keyed by a reverse-domain namespace (`:55-61`) |

`description` is free text. Nothing checks that it matches the skills you ship, so keep it accurate yourself: describe what the package contains today, not what you plan to add.

The schema is closed

`"additionalProperties": false` (`:64`), and `author` is closed too (`:38`). Any key outside the sets above is a schema violation. How CAO's validator reports one depends on where it is, and this was observed by running it:

• **An unknown key inside a defined object**, such as `author.twitter`, is

**FATAL** (`manifest.invalid`). The package is not loadable.

• **An unrecognized top-level key** is the one tolerance CAO's validator applies

(`_apply_manifest_tolerances` in `src/cli_agent_orchestrator/agent_plugins/validation.py`): a **WARNING** (`manifest.unknown_field`), the key is ignored, and the package still loads. The conformance fixture `test/agent_plugins/fixtures/corpus/manifest-unknown-field/` records exactly this outcome.

• **A non-object `extensions`** is likewise a WARNING and is ignored. A well-formed

`extensions` object is dropped without validating its contents, because CAO implements no extension namespace.

Do not rely on the tolerance. Against the schema an unknown key is invalid, and another conforming client is free to reject it. Put client-specific data in `extensions`, under a namespace you control.

Files the schema does not require

**`README.md`, `CHANGELOG.md` and `LICENSE` are not required by either vendored schem